ZulipChat MCP Server

ZulipChat MCP 服务

---

快速开始

uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

在 MCP 客户端中配置此命令，即可让助手使用已配置的账户读取和发送 Zulip 消息。

需要 zuliprc？Zulip Settings > Personal > Account & privacy > API key — 下载文件并将其保存为 ~/.zuliprc。

交互式入门：

uvx --from zulipchat-mcp zulipchat-mcp-setup

功能介绍

ZulipChat MCP 可将任何兼容 MCP 的 AI 助手（Claude Code、Gemini CLI、Cursor、Windsurf 等）接入你的 Zulip 工作区。助手可以：

• 发送和读取消息 — 获取消息流、私信、回复和反应
• 搜索对话历史 — 支持按发送者、消息流和时间范围筛选的全文搜索
• 按姓名查找人员 — 发送前确认收件人唯一；姓名存在歧义时需要澄清
• 切换身份 — 在同一会话中以本人或机器人身份发帖
• 监控活动 — 搜索近期消息、获取消息流信息、查看在线人员
• 将会话绑定到 Zulip 话题 — 为长时间运行的 Agent 会话指定稳定的控制话题
• 接收普通机器人提及 — 由事件馈送的本地收件箱，供你自己的主机适配器轮询，以唤醒 Agent 并在源话题中回复；对话无需使用 /reply。该服务负责传输，不会启动或监督编码 Agent
• 复用带日期的快照 — 短期消息缓存和感知速率限制的请求准入机制可减少重复 API 读取
• 在话题中请求审批 — 所有者在会话话题中回复 /approve REQUEST_ID 或 /deny REQUEST_ID；每项决定都会标明其对应的请求
• 加载 Agent Skills — 四项打包指令，涵盖消息发送、会话控制、通知和有界工作循环，可作为本地文件和 MCP 资源使用
• 导出 Agent 软件包 — 原生主机配置和技能、Claude 的钩子/插件资源，或 Agent Plugins 1.0.0 软件包

Agent 配置

# Substitute another supported client as needed.
uvx --from zulipchat-mcp zulipchat-mcp-integrate export --client clio-coder \
  --output-dir /absolute/path/to/project \
  --zulip-config-file /absolute/path/to/.zuliprc --extended-tools

导出支持 claude-code、codex、opencode、copilot、vscode、 antigravity-cli、clio-coder 和 generic。添加 --mode plugin 以生成软件包。 对于多个 Zulip 组织，请为每个组织分别导出一次，并使用 --server-id zulipchat-<org>；导出内容会合并到同一主机配置中。 账户状态存储在 ~/.local/state/zulipchat-mcp/ 下。主机信任仍需显式确认； Clio 会将 MCP 执行与插件内容分开配置。请参阅 功能矩阵、 Clio 指南和 完整工作流。

如需只读访问，请添加 --tool-profile read-only：发现和执行都会提供九个核心读取工具，或 23 个扩展读取工具。 默认的完整配置保留 20/60 个工具。请参阅API 覆盖范围与效率，了解缓存新鲜度、速率限制，以及消息传输与主机执行之间的边界。 实时 Luna 实验 记录了由私有、未发布的主机适配器驱动的真实 Clio TUI 中，正常的提及到机器人回复流程。 其他主机则通过导出的配置和伪凭据检查进行测试，而非实时会话。

双层工具架构

v0.6.0 引入了刻意区分的两种模式：默认提供 20 个核心工具，需要更多时可使用 60 个工具。

核心模式（默认）

涵盖大多数日常用途的 20 个工具：

类别	工具
消息	send_message、edit_message、get_message、add_reaction
搜索	search_messages、get_streams、get_stream_info、get_stream_topics
用户	resolve_user、get_users、get_own_user
Agent 通信	teleport_chat、register_agent、ensure_agent_session、agent_message、request_user_input、wait_for_response
系统	switch_identity、server_info、manage_message_flags

为什么是 20 个而不是 60 个？工具越少，工具选择越快、令牌开销越低，AI 也更不容易混淆。大多数任务——发送消息、搜索、添加反应，以及将 Agent 会话绑定到 Zulip——只需要核心工具集。

扩展模式

需要定时消息、事件队列、文件上传、分析或高级搜索？

uvx zulipchat-mcp --zulip-config-file ~/.zuliprc --extended-tools

或通过环境变量启用：

ZULIPCHAT_EXTENDED_TOOLS=1 uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

扩展模式还会添加：toggle_reaction、cross_post_message、advanced_search、construct_narrow、get_scheduled_messages、manage_scheduled_message、get_drafts、create_draft、edit_draft、delete_draft、register_events、get_events、listen_events、upload_file、manage_files、get_daily_summary、manage_user_mute、get_user、get_presence、get_user_groups 等。

安装

各客户端的完整配置指南：docs/integrations/README.md

Claude Code

claude mcp add zulipchat -- uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

使用双重身份（你 + 一个机器人）：

claude mcp add zulipchat -- uvx zulipchat-mcp \
  --zulip-config-file ~/.zuliprc \
  --zulip-bot-config-file ~/.zuliprc-bot

可选的 Claude 钩子桥接，用于生命周期管理和审批路由：

uvx --from zulipchat-mcp zulipchat-mcp-hook \
  --zulip-config-file ~/.zuliprc \
  --zulip-bot-config-file ~/.zuliprc-bot

可选的 Claude 软件包导出，用于项目本地钩子、技能和子 Agent：

uvx --from zulipchat-mcp zulipchat-mcp-integrate export \
  --client claude-code \
  --mode standalone \
  --output-dir . \
  --zulip-config-file ~/.zuliprc \
  --zulip-bot-config-file ~/.zuliprc-bot

Gemini CLI

在 ~/.gemini/settings.json 的 mcpServers 下添加：

{
  "zulipchat": {
    "command": "uvx",
    "args": ["zulipchat-mcp", "--zulip-config-file", "/path/to/.zuliprc"]
  }
}

Claude Desktop / Cursor / 任意 MCP 客户端

添加到 MCP 配置中：

{
  "mcpServers": {
    "zulipchat": {
      "command": "uvx",
      "args": ["zulipchat-mcp", "--zulip-config-file", "/path/to/.zuliprc"]
    }
  }
}

配置选项

选项	描述
--zulip-config-file PATH	zuliprc 文件的路径
--zulip-bot-config-file PATH	用于双重身份的 Bot zuliprc
--extended-tools	注册全部 60 个工具，而非 20 个核心工具
--tool-profile {full,read-only}	筛选工具发现结果并强制使用只读 Zulip 调用；默认值：full
--transport {stdio,http}	提供服务的传输方式（默认值：stdio）
--host HOST	HTTP 传输的绑定主机（默认值：127.0.0.1）
--port PORT	HTTP 传输的绑定端口（默认值：8000）
--auth-token TOKEN	HTTP 传输的 Bearer 认证令牌（或使用 ZULIPCHAT_HTTP_AUTH_TOKEN）
--allowed-host HOST	额外的受信任 HTTP 主机名；可重复指定多个名称
--allowed-origin URL	额外的受信任浏览器来源；可重复指定多个来源
--unsafe	启用管理工具（请谨慎使用）
--debug	启用调试日志记录
--associate-existing-db	将未绑定的旧版数据库主动关联到已验证的当前账户

远程 HTTP 传输

ZulipChat MCP 支持在 MCP 2026-07-28 协议下进行无状态 HTTP 部署：

# Run server over HTTP with bearer authentication
ZULIPCHAT_HTTP_AUTH_TOKEN=your-secret-token \
  uvx zulipchat-mcp --zulip-config-file ~/.zuliprc --transport http --host 0.0.0.0 --port 8000 --allowed-host mcp.internal

生成远程 HTTP 连接的客户端集成片段：

uvx --from zulipchat-mcp zulipchat-mcp-integrate print --client claude-code --remote-url http://mcp.internal:8000/mcp --remote-token your-secret-token

非回环绑定的 HTTP 启动需要 Bearer 令牌，并会验证 Host 和 Origin 标头。为客户端或反向代理使用的主机名配置 --allowed-host；远程连接应在代理处终止 TLS。令牌授予对已配置 Zulip 账户的访问权限：每个受信任的账户应部署独立实例，而不要在无关用户之间共享。

HTTP 工具不接受服务器本地文件路径、出站事件回调和 switch_identity。使用 file_content 上传文本，或使用 file_content_base64 上传二进制数据；下载时不指定 download_path，即可获取 URL。本地文件操作和运行时身份切换请使用 stdio。删除附件需要 --unsafe。

持久状态默认存储在按账户划分的目录中。显式指定的 ZULIPCHAT_DB_PATH 会与规范化后的 realm 及用户／Bot 主体关联；其他账户无法复用该路径。旧版状态会保留不变， 需要主动关联。请参阅数据库迁移。

Agent 会话、审批、监听器游标和默认的后台任务存储均属于本地状态。这些工作流请使用单个实例。使用不同的 DuckDB 路径可以避免写入冲突，但不会共享会话数据；不支持在此类副本之间进行常规的轮询路由。旧版 HTTP 客户端也可能保留传输会话。

AI 分析与大模型提供方

AI 分析工具（analyze_stream_with_llm、analyze_team_activity_with_llm、intelligent_report_generator）通过服务器端 Anthropic 大模型提供方执行：

• 在服务器进程中设置 ANTHROPIC_API_KEY，以启用大模型生成。
• 可选设置 ANTHROPIC_MODEL，以覆盖默认模型（claude-opus-5）。
• 如果未设置 API 密钥，分析工具会返回包含 llm_unavailable: true 的结构化数据摘要，供客户端助手直接分析数据。

更多客户端

专用设置页面：

• Gemini CLI
• Codex
• OpenCode
• VS Code + GitHub Copilot
• Cursor
• Windsurf
• Antigravity
• 通用 MCP

双重身份

同时配置用户和 Bot 的 zuliprc，即可让助手在会话期间切换身份：

uvx zulipchat-mcp \
  --zulip-config-file ~/.zuliprc \
  --zulip-bot-config-file ~/.zuliprc-bot

默认情况下，助手会以你的身份发帖。调用 switch_identity 即可切换为 Bot 身份发帖，适用于自动通知、Agent 间通信，或区分人工消息与 Bot 消息。

真实场景示例

“告诉我今天 #engineering 里发生了什么” → 助手使用流和时间筛选条件调用 search_messages，总结相关讨论串。

“告诉团队我们下午 3 点部署” → 助手调用 send_message，向 #engineering 发送公告。

“关于 API 迁移的那条消息是谁发的？” → 助手使用关键词调用 search_messages，返回发送者和上下文。

“给 Sarah 的最后一条消息加上 :thumbs_up: 表情回应” → 助手先调用 resolve_user（“Sarah”），再调用 search_messages（发送者），然后调用 add_reaction。

“私信 Jaime，告诉他 PR 已准备就绪” → 助手调用 teleport_chat，通过模糊名称解析用户，无需电子邮件。

开发

git clone https://github.com/akougkas/zulipchat-mcp.git
cd zulipchat-mcp
uv sync
uv run zulipchat-mcp --zulip-config-file ~/.zuliprc

运行检查：

uv run pytest -q              # full test suite, 60% coverage gate
uv run ruff check .           # Linting
uv run mypy src               # Type checking

对于打包、依赖项、FastMCP 或启动方面的更改，请运行发布冒烟测试：

uv build
scripts/pre_release_smoke.sh --version X.Y.Z --allow-dirty

完整指南请参阅 CONTRIBUTING.md，AI Agent 指南请参阅 CLAUDE.md / AGENTS.md。

架构

src/zulipchat_mcp/
├── core/           # Client wrapper, identity, caching, security
├── tools/          # MCP tool implementations (two-tier registration)
├── services/       # Background listener and session event routing
├── utils/          # Logging, DuckDB persistence, metrics
└── config.py       # config loading (zuliprc + environment fallback)

本项目基于 FastMCP 构建，采用异步优先设计，使用 DuckDB 持久化 Agent 状态，并通过智能的用户 / 流缓存实现快速模糊解析。

隐私

• 不收集数据——除 Zulip API 调用外，任何内容都不会离开你的设备
• 不使用遥测——不进行任何分析、跟踪或使用情况报告
• 本地执行——所有处理都在你的硬件上进行
• 凭据保留在本地——API 密钥绝不会被记录，也不会传输到 Zulip 服务之外

完整政策：PRIVACY.md

许可证

MIT — 请参阅 LICENSE

链接

• 文档索引
• 支持
• 安全政策
• Zulip API 文档
• Model Context Protocol
• 报告问题
• 讨论

---