How do I install ZulipChat MCP Server?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does ZulipChat MCP Server need an API key?

The publisher lists these environment variables: ZULIP_EMAIL, ZULIP_API_KEY, ZULIP_SITE.

What transport does ZulipChat MCP Server use?

ZulipChat MCP Server runs locally over stdio.

When was ZulipChat MCP Server last checked?

Last checked 2026-11-09. ZulipChat MCP: Connect AI to Zulip with 60+ tools for messaging, streams, events, and analytics

ZulipChat MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx zulipchat-mcp==0.4.2

Credentials from the publisher

ZULIP_EMAIL — Your Zulip account email address
ZULIP_API_KEY — Your Zulip API key
ZULIP_SITE — Your Zulip server URL (e.g., https://yourorg.zulipchat.com)

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1ZULIP_EMAIL=<value> ZULIP_API_KEY=<secret> ZULIP_SITE=<value> claude mcp add io.github.akougkas-zulipchat -- uvx zulipchat-mcp==0.4.2

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.akougkas-zulipchat": {4      "command": "uvx",5      "args": [6        "zulipchat-mcp==0.4.2"7      ],8      "env": {9        "ZULIP_EMAIL": "<value>",10        "ZULIP_API_KEY": "<secret>",11        "ZULIP_SITE": "<value>"12      }13    }14  }15}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.4.2
API key

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

ZulipChat MCP Server

Quick Start · Setup Wizard · Integrations · Two-Tier Tools · Contributing

Quick Start

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

Configure this command in your MCP client to let the assistant read and write Zulip messages with the configured account.

Need a zuliprc? Zulip Settings > Personal > Account & privacy > API key — download the file, save it as ~/.zuliprc.

Interactive onboarding:

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

What This Does

ZulipChat MCP bridges any MCP-compatible AI assistant (Claude Code, Gemini CLI, Cursor, Windsurf, etc.) to your Zulip workspace. The assistant can:

Send and read messages — stream messages, DMs, replies, reactions
Search conversation history — full-text search with filters for sender, stream, time range
Resolve people by name — verify a unique recipient before sending; ambiguous names need clarification
Switch identities — post as yourself or as a bot, in the same session
Monitor activity — search recent messages, get stream info, check who's online
Bind sessions to Zulip topics — give long-running agent sessions a stable control topic
Receive ordinary bot mentions — an event-fed local inbox that your own host adapter polls to wake an agent and reply in the source topic, without /reply for conversation. The server is the transport; it does not launch or supervise coding agents
Reuse dated snapshots — short-lived message caches and rate-aware request admission reduce repeated API reads
Request approvals in-topic — owner replies with /approve REQUEST_ID or /deny REQUEST_ID in the session topic; each decision names the request it answers
Load Agent Skills — four packaged instructions for messaging, session control, notifications, and bounded work loops, available as local files and MCP Resources
Export agent packages — native host configuration and skills, Claude's hook/plugin assets, or an Agent Plugins 1.0.0 package

Agent setup

# Substitute another supported client as needed.
uvx --from zulipchat-mcp zulipchat-mcp-integrate export --client clio-coder \
  --output-dir /absolute/path/to/project \
  --zulip-config-file /absolute/path/to/.zuliprc --extended-tools

Exports support claude-code, codex, opencode, copilot, vscode, antigravity-cli, clio-coder, and generic. Add --mode plugin for a package. For several Zulip organizations, export once per organization with --server-id zulipchat-<org>; exports merge into one host configuration. Account state lives under ~/.local/state/zulipchat-mcp/. Host trust remains explicit; Clio configures MCP execution separately from plugin content. See the capability matrix, Clio guide, and complete workflow.

For read-only access, add --tool-profile read-only: discovery and execution both expose nine core reads or 23 extended reads. The default full profile retains 20/60 tools. See API coverage and efficiency for cache freshness, rate limits and the boundary between message transport and host execution. The live Luna experiment records normal mention-to-bot replies from a real Clio TUI driven by a private, unshipped host adapter. Other hosts were tested through exported configuration and fake-credential checks, not live sessions.

Two-Tier Tool Architecture

v0.6.0 introduced a deliberate split: 20 core tools by default, 60 tools when you need more.

Core Mode (default)

The 20 tools that cover most daily use:

Category	Tools
Messaging	`send_message`, `edit_message`, `get_message`, `add_reaction`
Search	`search_messages`, `get_streams`, `get_stream_info`, `get_stream_topics`
Users	`resolve_user`, `get_users`, `get_own_user`
Agent Comms	`teleport_chat`, `register_agent`, `ensure_agent_session`, `agent_message`, `request_user_input`, `wait_for_response`
System	`switch_identity`, `server_info`, `manage_message_flags`

Why 20 instead of 60? Fewer tools means faster tool selection, lower token overhead, and less confusion for the AI. Most tasks — sending messages, searching, reacting, and binding an agent session to Zulip — only need the core set.

Extended Mode

Need scheduled messages, event queues, file uploads, analytics, or advanced search?

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

Or via environment variable:

ZULIPCHAT_EXTENDED_TOOLS=1 uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

Extended mode adds: toggle_reaction, cross_post_message, advanced_search, construct_narrow, get_scheduled_messages, manage_scheduled_message, get_drafts, create_draft, edit_draft, delete_draft, register_events, get_events, listen_events, upload_file, manage_files, get_daily_summary, manage_user_mute, get_user, get_presence, get_user_groups, and more.

Installation

Full per-client setup guide: docs/integrations/README.md

Claude Code

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

With dual identity (you + a bot):

claude mcp add zulipchat -- uvx zulipchat-mcp \
  --zulip-config-file ~/.zuliprc \
  --zulip-bot-config-file ~/.zuliprc-bot

Optional Claude hook bridge for lifecycle and approval routing:

uvx --from zulipchat-mcp zulipchat-mcp-hook \
  --zulip-config-file ~/.zuliprc \
  --zulip-bot-config-file ~/.zuliprc-bot

Optional Claude package export for project-local hooks, skills, and subagents:

uvx --from zulipchat-mcp zulipchat-mcp-integrate export \
  --client claude-code \
  --mode standalone \
  --output-dir . \
  --zulip-config-file ~/.zuliprc \
  --zulip-bot-config-file ~/.zuliprc-bot

Gemini CLI

Add to ~/.gemini/settings.json under mcpServers:

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

Claude Desktop / Cursor / Any MCP Client

Add to your MCP configuration:

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

Configuration Options

Option	Description
`--zulip-config-file PATH`	Path to your zuliprc file
`--zulip-bot-config-file PATH`	Bot zuliprc for dual identity
`--extended-tools`	Register all 60 tools instead of the 20-tool core set
`--tool-profile {full,read-only}`	Filter discovery and enforce read-only Zulip calls; default: `full`
`--transport {stdio,http}`	Transport to serve on (default: `stdio`)
`--host HOST`	Bind host for HTTP transport (default: `127.0.0.1`)
`--port PORT`	Bind port for HTTP transport (default: `8000`)
`--auth-token TOKEN`	Bearer auth token for HTTP transport (or `ZULIPCHAT_HTTP_AUTH_TOKEN`)
`--allowed-host HOST`	Additional trusted HTTP hostname; repeat for multiple names
`--allowed-origin URL`	Additional trusted browser origin; repeat for multiple origins
`--unsafe`	Enable administrative tools (use with caution)
`--debug`	Enable debug logging
`--associate-existing-db`	Deliberately associate an unbound legacy database with the verified current account

Remote HTTP Transport

ZulipChat MCP supports stateless HTTP deployments under the MCP 2026-07-28 protocol:

# Run server over HTTP with bearer authentication
ZULIPCHAT_HTTP_AUTH_TOKEN=your-secret-token \
  uvx zulipchat-mcp --zulip-config-file ~/.zuliprc --transport http --host 0.0.0.0 --port 8000 --allowed-host mcp.internal

Generate client integration snippets for remote HTTP connections:

uvx --from zulipchat-mcp zulipchat-mcp-integrate print --client claude-code --remote-url http://mcp.internal:8000/mcp --remote-token your-secret-token

HTTP startup requires a bearer token for non-loopback binds and validates Host and Origin headers. Configure --allowed-host for the hostname used by clients or a reverse proxy; terminate TLS at the proxy for remote connections. A token grants access to the configured Zulip account: deploy a separate instance per trusted account, rather than sharing it across unrelated users.

HTTP tools reject server-local file paths, outbound event callbacks, and switch_identity. Upload text with file_content or binary bytes with file_content_base64; download without download_path to obtain a URL. Use stdio for local file operations and runtime identity switching. Attachment deletion requires --unsafe.

Persistent state defaults to an account-scoped directory. An explicitly selected ZULIPCHAT_DB_PATH is associated with the normalized realm and user/bot principals; a different account cannot reuse it. Legacy state is left intact and requires deliberate association. See database migration.

Agent sessions, approvals, listener cursors, and default background-task storage remain local state. Use a single instance for these workflows. Separate DuckDB paths avoid writer conflicts but do not share session data; ordinary round-robin routing across such replicas is not supported. Legacy HTTP clients may also retain transport sessions.

AI Analytics & LLM Provider

AI-powered analytics tools (analyze_stream_with_llm, analyze_team_activity_with_llm, intelligent_report_generator) execute using a server-side Anthropic LLM provider:

Set ANTHROPIC_API_KEY on the server process for LLM generation.
Optionally set ANTHROPIC_MODEL to override the default model (claude-opus-5).
Without an API key, analytics tools return structured data summaries with llm_unavailable: true so your client assistant can analyze the data directly.

More clients

Dedicated setup pages:

Dual Identity

Configure both a user and a bot zuliprc to let your assistant switch between identities mid-session:

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

The assistant posts as you by default. Call switch_identity to post as the bot — useful for automated notifications, agent-to-agent communication, or keeping human vs. bot messages distinct.

Real-World Examples

"Catch me up on what happened in #engineering today" → Assistant calls search_messages with stream + time filter, summarizes the thread.

"Tell the team we're deploying at 3pm" → Assistant calls send_message to #engineering with the announcement.

"Who sent that message about the API migration?" → Assistant calls search_messages with keywords, returns sender and context.

"React with :thumbs_up: to Sarah's last message" → Assistant calls resolve_user ("Sarah"), search_messages (sender), then add_reaction.

"DM Jaime that the PR is ready" → Assistant calls teleport_chat with fuzzy name resolution — no email needed.

Development

git clone https://github.com/akougkas/zulipchat-mcp.git
cd zulipchat-mcp
uv sync
uv run zulipchat-mcp --zulip-config-file ~/.zuliprc

Run checks:

uv run pytest -q              # full test suite, 60% coverage gate
uv run ruff check .           # Linting
uv run mypy src               # Type checking

For packaging, dependency, FastMCP, or startup changes, run the release smoke:

uv build
scripts/pre_release_smoke.sh --version X.Y.Z --allow-dirty

See CONTRIBUTING.md for the full guide, and CLAUDE.md / AGENTS.md for AI agent instructions.

Architecture

src/zulipchat_mcp/
├── core/           # Client wrapper, identity, caching, security
├── tools/          # MCP tool implementations (two-tier registration)
├── services/       # Background listener and session event routing
├── utils/          # Logging, DuckDB persistence, metrics
└── config.py       # config loading (zuliprc + environment fallback)

Built on FastMCP with async-first design, DuckDB for agent state persistence, and smart user/stream caching for fast fuzzy resolution.

Privacy

No data collection — nothing leaves your machine except Zulip API calls
No telemetry — zero analytics, tracking, or usage reporting
Local execution — all processing happens on your hardware
Credentials stay local — API keys are never logged or transmitted beyond your Zulip server

Full policy: PRIVACY.md

License

MIT — See LICENSE

ZulipChat MCP Server

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install ZulipChat MCP Server?

Does ZulipChat MCP Server need an API key?

What transport does ZulipChat MCP Server use?

When was ZulipChat MCP Server last checked?

Documentation

ZulipChat MCP Server

Quick Start

What This Does

Agent setup

Two-Tier Tool Architecture

Core Mode (default)

Extended Mode

Installation

Claude Code

Gemini CLI

Claude Desktop / Cursor / Any MCP Client

Configuration Options

Remote HTTP Transport

AI Analytics & LLM Provider

More clients

Dual Identity

Real-World Examples

Development

Architecture

Privacy

License

Links