Zulipchat MCP

🚀 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"]
    }
  }
}

配置選項

更多客戶端

以下是各客戶端的專用設置頁面：

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

💻 使用示例

基礎用法

以下是一些實際使用示例：

• “總結一下今天 #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% 的日常使用需求，具體分類如下：

選擇 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 API 文檔
• 模型上下文協議
• 報告問題
• 討論區