windborne/zulipmcp

Run AI agents in Zulip as @mentionable bots — or wire into any MCP client. Also works as a Python library.
Quickstart
1. Install the package:
2. Add a .zuliprc file to your project root with your Zulip bot credentials. See Add a bot or integration for instructions on making a bot. The bot type must be "generic."
3. Add the MCP server to your .mcp.json:
4. Restart your MCP client. The Zulip tools should now be available.
Read as yourself, post as a bot
A bot can't read private channels it isn't in or DMs it isn't part of. To let an agent read everything you can see while it still posts as the bot, run two servers: one on the bot's zuliprc, and a read-only one on a zuliprc holding your personal API key. Installing the zulipmcp command once keeps launches from re-resolving dependencies:
uv tool install ignores the lockfile; append @ to the URL to pin a version.
Desktop MCP clients often don't inherit your shell's PATH; if zulipmcp isn't found, use the absolute path under uv tool dir --bin.
__ALL__ lets that server read DMs and search everything the account received. Read-only mode constrains this server, not an agent that can read the personal zuliprc file itself.
Requirements
- Python >=3.10, managed with uv
- Zulip Server 9.0+ (before date bounds need 12.0+)
- A .zuliprc file for Zulip API auth (see Quickstart)
- For listener mode: the selected backend CLI installed and authenticated (claude by default, codex with --backend codex, or opencode with --backend opencode)
Entry Points
| Entry Point | Description |
|---|---|
| uv run python -m zulipmcp (or zulipmcp after uv tool install) | MCP server for Claude Code, Codex, and other MCP clients |
| uv run python -m zulipmcp --transport sse | MCP server over SSE (for remote/web clients) |
| uv run python -m zulipmcp.launch_agent | Launch one MCP-backed coding session without a listener |
| uv run python -m zulipmcp.listener | Listener: watches for @mentions, spawns agent sessions |
Library Usage
zulipmcp can also be imported directly as a Python library:
Hermes Gateway
Hermes uses the native hermes_plugin/zulip gateway
adapter instead of the subprocess listener. Each stream/topic maps to its own
persistent Hermes session, while zulipmcp remains available as the explicit
Zulip API tool layer.
- Mention the bot once to activate a topic; follow-ups do not need a mention.
- Each user message is a fresh Hermes turn with a fresh iteration budget.
- Typing, normal response delivery, status reactions, approval reactions,
and :stop_sign: interruption are handled by the adapter.
- Only same-topic history is added on first activation.
- After a gateway restart, mention once to reactivate the topic; Hermes resumes
the same stored session.
See the plugin README for installation,
configuration, access controls, and verification.
Direct launch (no listener)
An existing coordinator can start one Claude Code or Codex session directly.
The coding agent uses its configured zulip MCP server to initialize the
target topic, reply there, and wait for follow-ups:
The launcher does not watch Zulip or spawn on mentions. It starts exactly one
foreground coding-agent process and reuses the bundled session instructions.
Run it as a background process when the coordinator should continue working.
By default the agent listens in renewable two-hour intervals and does not exit
merely because an interval timed out.
Use --trigger-message-id and --session-user-email when that metadata is
available. Pass --zuliprc or --mcp-config only when the agent should not use
its existing global MCP configuration. An explicit Claude MCP config is loaded
strictly so a project-local server with the same name cannot shadow it.
Listener
The optional zulipmcp.listener module watches Zulip for @mentions and spawns one headless agent session per (stream, topic). It supports Claude Code by default, Codex with --backend codex, and OpenCode with --backend opencode. It's the glue between Zulip events and the agent backend -- the MCP server handles all the Zulip tools, the listener just handles lifecycle.