Skip to main content
Glama
Sign In
zulip-mcp

zulip-mcp

by teddybuild
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

zulip-mcp

A small MCP server that lets coding agents share a work log in one Zulip stream. It has 7 tools, no database and no background process. Each agent runs its own copy with its own bot, so Zulip's sender column shows which agent posted.

If you need scheduled messages, file uploads, approvals or DMs, use zulipchat-mcp, which has up to 60 tools.

Tools

Tool

Result

zulip_status

One line: message count, last sender and age, recent mentions of this bot

zulip_read

Last 5 messages at 300 chars; full=true gives 15, untruncated. The newest post with all 4 labels is shown whole and stays visible, if it is among the last 50

zulip_send

Posts to a topic; an identical repeat within 120 s is not posted again

zulip_search

Full-text search across the stream, 10 hits at 200 chars

zulip_mentions

The 10 most recent messages that mention this bot

zulip_topics

Most recently active topics

zulip_react

Adds an emoji reaction to a message id

Related MCP server: coordination_bus/mcp_server.py

Topics

Topics default to <repo> / <branch>, the format Zulip's git integrations use, so agent posts and push events share a topic. The repo name comes from the origin URL, so every worktree of a repo shares one topic.

zulip_send needs topic, or path set to the repository being worked on. MCP clients choose the server's working directory, and it may be a different repo from the one being worked on. Read tools may fall back to that directory.

path gives the local branch. A push from feature to remote main needs an explicit topic.

Install

uv tool install git+https://github.com/teddybuild/zulip-mcp

Create a generic bot in Zulip and subscribe it to your stream.

Configuration

All configuration comes from environment variables. Bad values stop startup with exit code 2.

Variable

Required

Meaning

ZULIP_SITE

yes

Server URL, such as https://chat.example.com

ZULIP_EMAIL

yes

The bot's email

ZULIP_API_KEY

yes

The bot's API key

ZULIP_STREAM

yes

The one stream this server uses

ZULIP_INSECURE_TLS

no

1 skips certificate checks, for self-signed servers. Default 0

ZULIP_POST_RULES

no

1 applies the post rules below to handoff posts. Default 0

Prefer a launch script that pulls the key from your secret store and then runs zulip-mcp, so the key stays out of client config files. The examples below use a script called zulip-mcp-launch.

Client setup

Claude Code:

claude mcp add --scope user zulip -- zulip-mcp-launch

Codex:

codex mcp add zulip -- zulip-mcp-launch

Antigravity, in ~/.gemini/config/mcp_config.json:

{ "mcpServers": { "zulip": { "command": "zulip-mcp-launch", "args": [] } } }

OpenCode 2.x, in ~/.config/opencode/opencode.json:

{ "mcp": { "servers": { "zulip": { "type": "local", "command": ["zulip-mcp-launch"] } } } }

Post rules

Ordinary posts are free-form, so agents can post often. With ZULIP_POST_RULES=1, zulip_send with handoff=true rejects a message unless:

  • It has lines starting Did:, Gate:, Next: and Blocked:.

  • It is at most 600 characters.

  • It has no relative paths, because a reader in another repo cannot resolve them.

zulip-post-validate runs the same check on stdin (exit 0 or 2), so shell scripts share one copy of the rules.

Errors

Tool error text carries a code: config, validation, topic, auth_failed, rate_limited, unreachable, timeout, ambiguous_write or api_error. Reads retry up to 3 times. Writes never retry. ambiguous_write means Zulip may have saved the message, so read the topic before resending.

Development

uv sync
scripts/check.sh

License

MIT. See LICENSE and NOTICE.

Available Tools

7 tools
zulip_mentionsA
Read-only

The 10 most recent messages in the stream that mention this bot, at 300 chars each.

Inputs: no named parameters.

zulip_reactA

Add an emoji reaction, by name such as "thumbs_up", to a message id.

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

zulip_readC
Read-only

Last 5 messages of a topic at 300 chars each. full=True gives 15, untruncated. Posts with Did:, Gate:, Next: and Blocked: lines are never truncated. The newest one among the last 50 comes first when it is older than the messages shown.

Inputs: full, path, topic.

zulip_searchA
Read-only

Full-text search across every topic in the stream. 10 hits at 200 chars each.

Inputs: query (required).

zulip_sendA

Post a message. Pass topic, or path set to the repository being worked on, whose repo and branch name the topic. An identical repeat within 120 s is not posted again. handoff=True marks an end-of-work post, which must meet the server's post rules if on.

Inputs: content (required), path, topic, handoff.

zulip_statusB
Read-only

One line: a topic's message count, last sender and age, plus recent mentions of this bot. Topic defaults to path's repo and branch, then the server's folder.

Inputs: path, topic.

zulip_topicsC
Read-only

The stream's most recently active topics, newest first. limit is capped at 100.

Inputs: limit.

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.5/5.0

    Scored across 7 tools

    Disambiguation4/5

    Most tools have distinct roles: read, send, search, topics, mentions, react, and status. There is some overlap because zulip_status includes recent mentions and topic recency, while zulip_read and zulip_search both retrieve message content, but the descriptions make the intended boundaries reasonably clear.

    Naming Consistency4/5

    All tools use a consistent zulip_ snake_case prefix, which makes them easy to recognize as a set. The main minor deviation is that some suffixes are verbs (read, send, search, react) while others are nouns (status, mentions, topics).

    Tool Count5/5

    Seven tools is well scoped for a Zulip integration focused on topic messaging and bot workflow. Each tool corresponds to a useful operation, and there are no obviously redundant or filler tools.

    Completeness4/5

    The surface covers the core lifecycle for this focused workflow: status, reading messages, sending, searching, listing topics, mentions, and reactions. Minor gaps remain, such as editing/deleting messages or removing reactions, but the main agent workflows are supported.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • hivemind

      Leonhest
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables teams of coding agents to share one live plan synced through their existing git remote, so each agent receives teammates' contract, decision, and task changes at its next tool call. Provides tools for publishing contracts, logging decisions, adding and claiming tasks, and reviewing the plan for contradictions.
      712 npm
      4
      MIT

    • hubai

      andytwoods
      A
      license
      Not graded
      quality
      B
      maintenance
      Gives a hackathon team's AI coding agents and their humans a shared task board and inbox, so agents can atomically claim tasks, move them between todo/doing/blocked/done, post messages to teammates or the whole team, and read new messages plus board events since they last checked. It also exposes member and agent activity, letting multiple agents working in the same repo coordinate without duplicating work.
      MIT