Zulip MCP Server
# Zulip MCP Server
MCP server that lets Claude Code (or any MCP client) talk to a Zulip workspace: post to channels,
send DMs, react, read history, and poll for messages that @-mention the bot.
Fork of [Monadical-SAS/zulip-mcp](https://github.com/Monadical-SAS/zulip-mcp) with an added
`zulip_get_my_mentions` tool and an opt-in for self-signed certificates.
Requires Node.js 18+.
## 1. Get a bot key
In Zulip: **Settings → Personal → Bots → Add a new bot → Generic bot**. Note the bot's email and
API key. Subscribe the bot to the channels it should read.
Keep the API key private; don't commit it or paste it in chat.
## 2. Install
### Option A: clone (recommended)
```bash
git clone https://github.com/ahmadjan223/zulip-mcp.git
cd zulip-mcp
npm install # also builds dist/index.js
```
Register it with Claude Code (use the absolute path to your clone):
```bash
claude mcp add zulip --scope user \
-e ZULIP_URL=https://your-zulip-host \
-e ZULIP_EMAIL=your-bot@your-zulip-host \
-e ZULIP_API_KEY=your-bot-api-key \
-- node /absolute/path/to/zulip-mcp/dist/index.js
```
Update later with `git pull && npm install`, then reconnect via `/mcp` in Claude Code.
### Option B: no clone, via npx
```bash
claude mcp add zulip --scope user \
-e ZULIP_URL=https://your-zulip-host \
-e ZULIP_EMAIL=your-bot@your-zulip-host \
-e ZULIP_API_KEY=your-bot-api-key \
-- npx -y github:ahmadjan223/zulip-mcp
```
npx fetches and builds it on first start, so the first connection takes a little longer.
### Check it works
Open Claude Code and run `/mcp`; `zulip` should show as connected.
## Environment variables
| Variable | Required | Meaning |
|---|---|---|
| `ZULIP_URL` | yes | Zulip server URL, e.g. `https://zulip.example.com` |
| `ZULIP_EMAIL` | yes | The bot's email |
| `ZULIP_API_KEY` | yes | The bot's API key |
| `ZULIP_INSECURE_TLS` | no | Set to `1` to accept a self-signed certificate (self-hosted / LAN Zulip) |
### Self-hosted Zulip on a LAN
If the Zulip server runs on a teammate's machine (e.g. `docker-zulip` with a self-signed cert at
`https://zulip.localhost`):
1. Point the hostname at that machine in `/etc/hosts`: `192.168.x.x zulip.localhost`
2. Add `-e ZULIP_INSECURE_TLS=1` to the `claude mcp add` command.
## Tools
- `zulip_get_my_mentions`: messages that @-mention the bot or DM it, across all channels.
Optional `since_message_id` (returns only newer ones) and `limit` (default 20). Returns
`latest_message_id` to pass back on the next poll.
- `zulip_list_channels`: list channels. Optional `include_private`, `include_web_public`,
`include_subscribed`.
- `zulip_post_message`: post to a channel. `channel_name`, `topic`, `content`.
- `zulip_send_direct_message`: DM users. `recipients` (emails or ids), `content`.
- `zulip_add_reaction`: react to a message. `message_id`, `emoji_name` (no colons).
- `zulip_get_channel_history`: messages in a channel topic. `channel_name`, `topic`; optional
`limit`, `anchor`.
- `zulip_get_topics`: topics in a channel. `channel_id`.
- `zulip_subscribe_to_channel`: subscribe the bot. `channel_name`.
- `zulip_get_users`: list users in the organization.
### Example: answer mentions on a loop in Claude Code
```
/loop 1m Call zulip_get_my_mentions with since_message_id = the last id you handled, answer each new message, and reply in the same channel/topic (or by DM if it was a DM).
```
## Troubleshooting
- **`/mcp` shows failed:** check the three required env vars, and that the Zulip URL opens in a browser.
- **Certificate errors:** add `ZULIP_INSECURE_TLS=1` (self-signed servers only).
- **No messages from a channel:** subscribe the bot to it.
## License
Apache License 2.0. Original work copyright 2025 Monadical; see [LICENSE](LICENSE) and
[NOTICE](NOTICE).
TDQS
Scored across 9 tools
Most tools target a clearly distinct resource+action: channel listing, channel posting, DM sending, reactions, topics, subscriptions, and users are all separable. The only mild overlap is between zulip_get_channel_history and zulip_get_my_mentions, which both return messages but with different scopes (single channel/topic vs. cross-channel mentions/DMs), and descriptions make that distinction clear.
All nine tools follow a uniform zulip_<verb>_<noun> snake_case pattern (zulip_list_channels, zulip_post_message, zulip_get_topics, etc.). Verb choices vary (post/send/add/list/get) but each verb fits its object naturally rather than reflecting inconsistency.
Nine tools is well within the ideal 3-15 range for a chat-platform integration and each one maps to a distinct Zulip primitive. No tool feels redundant or like padding.
Core read/write flows are covered (list channels, post to channel, send DM, topics, history, mentions, users), but the message lifecycle is incomplete: there is no edit/update message, delete message, or remove-reaction operation, and no way to fetch direct-message history with a specific user. Agents wanting to correct or clean up messages will hit dead ends.