Skip to main content
Glama
Zulip MCP Server
by ahmadjan223

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 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.

Related MCP server: ZulipChat MCP Server

2. Install

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):

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

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 and NOTICE.

Available Tools

9 tools
zulip_add_reactionC

Add an emoji reaction to a message

Inputs: emoji_name (required), message_id (required).

zulip_get_channel_historyC

Get recent messages from a channel (stream) and topic

Inputs: topic (required), channel_name (required), limit, anchor.

zulip_get_my_mentionsA

Get messages that @-mention this bot or are direct messages to it, across all channels. Pass since_message_id (the highest id you've already handled) to get only newer ones. Returns plain-text messages with id, channel, topic and sender, oldest first.

Inputs: limit, since_message_id.

zulip_get_topicsB

Get topics in a channel (stream)

Inputs: channel_id (required).

zulip_get_usersB

Get list of users in the Zulip organization

Inputs: no named parameters.

zulip_list_channelsC

List available channels (streams) in the Zulip organization

Inputs: include_private, include_subscribed, include_web_public.

zulip_post_messageC

Post a new message to a Zulip channel (stream)

Inputs: topic (required), content (required), channel_name (required).

zulip_send_direct_messageC

Send a direct message to one or more users

Inputs: content (required), recipients (required).

zulip_subscribe_to_channelB

Subscribe the bot to a channel (stream)

Inputs: channel_name (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Bridges MCP-compatible AI assistants to Zulip chat, enabling message sending/receiving, search, user resolution, and dual-identity support.
      33
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes Zulip REST API tools via SSE, enabling message retrieval, stream/topic listing, draft management, and notifications.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to list Slack channels, post and reply to messages, add reactions, and retrieve channel history, thread replies, users, and user profiles through the Slack Web API.
      74 npm
      MIT