Skip to main content
Glama
Zulip MCP Server
by ahmadjan223
README.md
# 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

A3.5/5.0

Scored across 9 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness3/5

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.