zulipmcp

在 Zulip 中将 AI 代理作为可 @提及的机器人运行，或接入任何 MCP 客户端。也可以作为 Python 库使用。

快速入门

1. 安装软件包：

   uv add zulipmcp --git https://github.com/windborne/zulipmcp.git

2. 在项目根目录添加一个 .zuliprc 文件，填入你的 Zulip 机器人凭据。有关创建机器人的说明，请参阅 添加机器人或集成。机器人类型必须为“通用 (generic)”。

3. 将 MCP 服务器添加到你的 .mcp.json 中：

   {
     "mcpServers": {
       "zulip": {
         "command": "uv",
         "args": ["run", "python", "-m", "zulipmcp.mcp"]
       }
     }
   }

4. 重启你的 MCP 客户端。现在应该可以使用 Zulip 工具了。

要求

• Python >=3.10，使用 uv 管理

• 用于 Zulip API 认证的 .zuliprc 文件（参见 快速入门）

入口点

库用法

zulipmcp 也可以直接作为 Python 库导入：

import zulipmcp

# Fetch and format recent messages
messages = zulipmcp.get_messages(hours_back=24, channels=["engineering"])
print(zulipmcp.format_messages(messages))

# Send a message
zulipmcp.send_message("engineering", "general", "Hello from Python!")

# Configure MCP hooks before starting the server
zulipmcp.configure(
    message_prefix=lambda: "[bot] ",
    on_session_end=lambda session: print(f"Session ended in #{session.stream}"),
)

监听器

可选的 zulipmcp.listener 模块会监视 Zulip 中的 @提及，并为每个（流，主题）启动一个无头 Claude Code 会话。它是 Zulip 事件与 Claude Code 之间的粘合剂——MCP 服务器处理所有 Zulip 工具，而监听器仅处理生命周期。

# Minimal -- uses ./.zuliprc, ./.mcp.json (if present), and the bundled default prompt
uv run python -m zulipmcp.listener

# Full -- override MCP config and system prompt
uv run python -m zulipmcp.listener \
    --mcp-config .mcp.json \
    --system-prompt agent.md \
    --log-dir ./logs

# Pass flags through to Claude Code (everything after --)
uv run python -m zulipmcp.listener -- --strict-mcp-config --model opus

标志：

每个会话都会自动设置 TRIGGER_MESSAGE_ID 和 SESSION_USER_EMAIL，以便 set_context() 锚定到 @提及，并让钩子 (hooks) 识别请求者。

该监听器刻意保持极简（约 230 行）。它省略了并发限制、工作区隔离、陈旧监视器和仪表板——当你需要时可以自行添加。

关键设计细节

监听消息

listen 工具使用 Zulip 的 实时事件 API（长轮询），而不是重复调用 GET /messages。进入时，它会补全自 last_seen_message_id 以来的所有消息，在需要时将机器人订阅到流，为该流/主题注册一个缩小的事件队列，然后通过 GET /events 进行长轮询。服务器会阻塞直到消息到达或约 90 秒过去（心跳），这比每 2 秒轮询一次的效率高出约 30 倍。如果队列过期 (BAD_EVENT_QUEUE_ID)，它会自动重新注册。队列在退出时的 finally 块中被删除。

监听时，会在最后一条消息上添加一个 robot_ear 表情符号作为视觉指示器，并在停止监听时移除。MCP 保活 ping 会在每个长轮询周期后通过 ctx.info() 发送。

回复时不漏掉消息

调用 reply 时，它会在发送前检查是否有新消息。如果 LLM 在思考时有人发布了消息，这些消息会被获取并与“消息已发送”确认一起返回。这样 LLM 总能看到它错过的消息并做出相应反应。last_seen_message_id 会更新为最新的一条（无论是错过的消息还是发送的消息），确保没有任何内容被遗漏。

会话注销

用户可以通过在任何机器人消息上添加可配置的表情符号（默认：:stop_sign:）来注销机器人会话。注销检查在 listen() 期间（通过反应事件）和 reply() 之前（通过 REST API 轮询）都会运行，涵盖了用户在机器人忙碌时做出反应的竞态条件。可以通过 configure(dismiss_emoji={"stop_sign", "wave"}) 进行自定义。

机器人可见性过滤

包含 /nobots 或 /nb 的主题对机器人完全隐藏。以 /nobots 或 /nb 开头的消息也会被过滤掉。这允许人类进行机器人无法看到的私人对话。

环境变量

许可证

MIT