ZulipChat MCP Server

How to use

You use the Zulip MCP server by connecting an MCP client to it. Once connected, your AI assistant can perform actions across eight categories such as Messaging, Streams, Topics, Users, Search & Analytics, Events, Files, and System workflows. Start by configuring your MCP client to point at the server, then invoke tool endpoints or commands supported by the client to send messages, query streams, manage topics, retrieve analytics, upload files, listen for events, and execute automated workflows. The server handles authentication against Zulip using your provided credentials and exposes capabilities through a consistent MCP interface so your AI can act within Zulip with proper context.

How to install

Prerequisites: you need Python 3.10+ and the UV package manager. You will also need access to a Zulip instance and a zuliprc configuration file that contains your Zulip credentials.

uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

If you prefer a wizard-assisted setup, run the setup flow to automatically locate zuliprc files, validate credentials, and generate the MCP client configuration.

uvx --from zulipchat-mcp zulipchat-mcp-setup

If you want to connect manually using a Zulip config file, you can use the following approach.

uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

A sample MCP configuration for an MCP client can be added to your MCP config file as shown in the example below. This enables you to run the MCP server from a local command, such as during development or testing.

{
  "mcpServers": {
    "zulipchat": {
      "command": "uvx",
      "args": ["zulipchat-mcp", "--zulip-config-file", "/path/to/zuliprc"]
    }
  }
}

Configuration & troubleshooting

Configuration options you may encounter include specifying the zuliprc path, enabling a bot configuration file for dual identity, and toggling debugging or listener services. Use the following options when running the client or setting up the MCP config file: --zulip-config-file PATH, --zulip-bot-config-file PATH, --unsafe, --debug, and --enable-listener.

Common issues and their remedies include ensuring your Zulip credentials are correct, confirming the Zulip site URL uses https, and verifying your bot has permissions for the streams you intend to use. If a connection fails, validate the credentials and recheck the zuliprc file. If a module cannot be found, consider updating the UV toolchain and reinstalling the MCP package.

For troubleshooting, ensure the MCP client config is correctly referenced by the server and that the command or URL used to start the MCP server is valid and reachable.

message

Send, schedule, or draft messages with smart formatting and context-aware behavior.

search_messages

Query messages with token-limited results and narrow filters to locate relevant content.

edit_message

Edit message content and topics with propagation options.

bulk_operations

Coordinate and monitor large-scale messaging tasks with progress tracking.

message_history

Provide an audit trail of messages with timestamps for edits and actions.

cross_post_message

Share messages across streams with attribution and proper formatting.

add_reaction

Attach reactions to messages using Unicode or custom emotes; supports removal.

remove_reaction

Remove reactions from messages to manage engagement.

mark_read

Set messages as read to track user engagement.

mark_unread

Mark messages as unread to surface attention when needed.

schedule_message

Schedule messages for delayed delivery; option to cancel scheduled items.

cancel_scheduled

Cancel previously scheduled messages.

get_stream_info

Fetch details about a Zulip stream, including subscribers and configurations.

list_streams

List streams with filters such as subscription status for quick discovery.

list_topics

List topics within a selected stream to navigate conversations.

manage_topics

Move topics across streams and apply propagation rules where supported.

manage_users

Handle multiple identity contexts; switch between user and bot roles.

switch_identity

Validate and switch the current session identity for continuity.

manage_user_groups

Create and manage user groups and memberships in Zulip.

get_presence

Query user online presence to gauge availability.

set_status

Set a user's status emoji and text to reflect current state.

mute_user

Mute a user to suppress notifications from specific individuals.

unmute_user

Unmute a user to resume normal notifications.

advanced_search

Perform multi-criteria searches with ranking and filters.

analytics

Generate AI-powered insights, sentiment analysis, and participation metrics.

get_daily_summary

Produce activity summaries and engagement reporting.

register_events

Subscribe to 20+ event types with queue auto-cleanup.

get_events

Receive long-polling updates with queue validation for real-time data.

delete_queue

Clean up event queues when no longer needed.

listen_events

Integrate with webhooks to receive event notifications.

upload_file

Upload files with progress tracking and automatic sharing.

manage_files

Handle file lifecycles, including metadata extraction.

server_info

Retrieve server metadata and routing hints for debugging.

tool_help

Provide on-demand tool documentation to users.

execute_chain

Run workflows with branching logic and conditional steps.

register_agent

Track agent sessions and identities in the MCP environment.

agent_message

Send bot identity messages to establish or update bot personas.