JinDaGe - zulipchat-mcp MCP Details

article

README

🚀 ZulipChat MCP 服务器

ZulipChat MCP 服务器是用于 Zulip 聊天的模型上下文协议（MCP）服务器。它可以将 Claude Code、Gemini CLI、Codex、Cursor、Windsurf、VS Code Copilot 等 MCP 客户端连接到 Zulip。

快速开始 · 设置向导 · 集成 · 两层工具架构 · 贡献代码

🚀 快速开始

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

完成以上操作后，你的 AI 助手就可以读写 Zulip 消息了。

如果你还没有 zuliprc 文件，可以在 Zulip 设置 > 个人 > 账户与隐私 > API 密钥 中下载该文件，并将其保存为 ~/.zuliprc。

你也可以通过以下命令进行交互式设置：

uvx zulipchat-mcp-setup

✨ 主要特性

ZulipChat MCP 能够将任何兼容 MCP 的 AI 助手（如 Claude Code、Gemini CLI、Cursor、Windsurf 等）连接到你的 Zulip 工作区。该助手可以实现以下功能：

收发消息：支持流式消息、直接消息、回复和反应。
搜索对话历史：支持全文搜索，并可根据发送者、流和时间范围进行过滤。
按名称查找人员：例如输入 "给 Jaime 发消息" 即可直接操作，无需查找正式邮箱。
切换身份：可以在同一会话中以你自己或机器人的身份发布消息。
监控活动：搜索最近的消息、获取流信息以及查看在线人员。

📦 安装指南

完整的每个客户端的设置指南请参考：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

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 | 用于双重身份的机器人 zuliprc 文件路径 | | --extended-tools | 注册约 55 个工具，而不是默认的 19 个 | | --unsafe | 启用管理工具（使用时请谨慎） | | --debug | 启用调试日志记录 |

💻 使用示例

基础用法

以下是一些实际使用示例：

“总结一下今天 #engineering 频道发生的事情”：助手调用 search_messages 并结合流和时间过滤器，然后总结线程内容。
“告诉团队我们下午 3 点部署”：助手调用 send_message 向 #engineering 频道发送公告。
“谁发了关于 API 迁移的消息？”：助手调用 search_messages 并使用关键词搜索，然后返回发送者和上下文信息。
“给 Sarah 的最后一条消息点个赞”：助手先调用 resolve_user 查找 “Sarah”，再调用 search_messages 查找发送者，最后调用 add_reaction 进行点赞操作。
“给 Jaime 发消息说 PR 已准备好”：助手调用 teleport_chat 并使用模糊名称解析，无需输入邮箱地址。

🔧 技术细节

两层工具架构

从 v0.6.0 版本开始，该项目引入了两层工具架构，默认提供 19 个核心工具，在需要时可扩展到约 55 个工具。

核心模式（默认）

这 19 个工具可以满足 95% 的日常使用需求，具体分类如下： | 类别 | 工具 | |----------|-------| | 消息传递 | 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 | | 代理通信 | teleport_chat, register_agent, agent_message, request_user_input, wait_for_response | | 系统 | switch_identity, server_info, manage_message_flags |

选择 19 个工具而非 55 个以上的原因在于，较少的工具可以加快工具选择速度，减少令牌开销，并降低 AI 的困惑。大多数任务（如发送消息、搜索和添加反应）只需要核心工具集。

扩展模式

如果你需要定时消息、事件队列、文件上传、分析或高级搜索等功能，可以使用以下命令启用扩展模式：

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, register_events, get_events, listen_events, upload_file, manage_files, get_daily_summary, manage_user_mute, get_user, get_presence, get_user_groups 等。

项目架构

src/zulipchat_mcp/
├── core/           # 客户端包装器、身份、缓存、安全
├── tools/          # MCP 工具实现（两层注册）
├── services/       # 后台监听器、离开状态监视器
├── utils/          # 日志记录、DuckDB 持久化、指标
└── config.py       # 配置加载（zuliprc + 环境变量备用）

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

隐私保护

无数据收集：除了 Zulip API 调用外，没有任何数据离开你的机器。
无遥测：不进行任何分析、跟踪或使用情况报告。
本地执行：所有处理都在你的硬件上进行。
凭证本地保存：API 密钥不会被记录或传输到你的 Zulip 服务器之外。

完整的隐私政策请参考：PRIVACY.md

📄 许可证

本项目采用 MIT 许可证，详情请见 LICENSE。

🔗 相关链接

_{为 Zulip 社区构建}

zulipchat-mcp