ZulipChat MCP服务器
Model Context Protocol server for Zulip Chat. Connect Claude Code, Gemini CLI, Codex, Cursor, Windsurf, VS Code Copilot, and other MCP clients to Zulip.
快速开始```bash
uvx zulipchat-mcp --zulip-config-file ~/.zuliprc
就是这样。你的人工智能助手现在可以读写Zulip消息了。
需要zulipc吗? **Zulip设置>个人>帐户和隐私>API密钥** --下载文件,另存为 `~/.zuliprc`.
互动式入职培训:```bash
uvx --from zulipchat-mcp zulipchat-mcp-setup
这有什么作用
ZulipChat MCP将任何兼容MCP的AI助手(Claude Code、Gemini CLI、Cursor、Windsurf等)连接到您的Zulip工作区。助理可以:
- 发送和阅读消息 --流式消息、DM、回复、反应
- 搜索对话历史记录 --使用发件人、流、时间范围筛选器进行全文搜索
- 按名称解析人员 --“消息詹姆”只是有效的,不需要寻找正式的电子邮件
- 交换机标识 --在同一会话中以自己或机器人的身份发布
- 监督活动 --搜索最近的消息,获取流信息,检查谁在线
- 将会话绑定到Zulip主题 --为长时间运行的代理会话提供一个稳定的控制主题
- 请求主题中的批准 --所有者回复如下
approve/deny在会议主题中
两层工具架构
v0.6.0引入了一个深思熟虑的拆分: 20个核心工具 默认情况下, 56工具 当你需要更多的时候。
核心模式(默认)
涵盖大多数日常使用的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 |
| 代理通信 | teleport_chat, register_agent, ensure_agent_session, agent_message, request_user_input, wait_for_response |
| 系统 | switch_identity, server_info, manage_message_flags |
为什么是20而不是56?更少的工具意味着更快的工具选择、更低的令牌开销和更少的人工智能混淆。大多数任务——发送消息、搜索、反应和将代理会话绑定到Zulip——只需要核心集。
扩展模式
需要定时消息、事件队列、文件上传、分析或高级搜索?```bash
uvx zulipchat-mcp --zulip-config-file ~/.zuliprc --extended-tools
或者通过环境变量:```bash
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以及更多。
安装
完整的每个客户端设置指南: docs/integrations/README.md
克劳德代码```bash
claude mcp add zulipchat -- uvx zulipchat-mcp --zulip-config-file ~/.zuliprc
双重身份(你+机器人):```bash
claude mcp add zulipchat -- uvx zulipchat-mcp \
--zulip-config-file ~/.zuliprc \
--zulip-bot-config-file ~/.zuliprc-bot
可选的克劳德钩桥,用于生命周期和审批流程:```bash
uvx zulipchat-mcp-hook \
--zulip-config-file ~/.zuliprc \
--zulip-bot-config-file ~/.zuliprc-bot
可选的Claude包导出,用于项目本地钩子、技能和子代理:```bash
uvx 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:```json
{
"zulipchat": {
"command": "uvx",
"args": ["zulipchat-mcp", "--zulip-config-file", "/path/to/.zuliprc"]
}
}
### 克劳德桌面/光标/任何MCP客户端
添加到MCP配置中:```json
{
"mcpServers": {
"zulipchat": {
"command": "uvx",
"args": ["zulipchat-mcp", "--zulip-config-file", "/path/to/.zuliprc"]
}
}
}
配置选项
| 选项 | 描述 |
|---|---|
--zulip-config-file PATH |
zulipc文件的路径 |
--zulip-bot-config-file PATH |
Bot zulipc用于双重身份 |
--extended-tools |
注册所有56个工具,而不是20个工具核心集 |
--unsafe |
启用管理工具(谨慎使用) |
--debug |
启用调试日志记录 |
更多客户
专用设置页面:
- Gemini CLI
- 法典
- OpenCode
- VS代码+GitHub副本
- 光标
- 帆板运动
- 反重力
- 通用MCP
双重身份
配置一个用户和一个bot-zulipc,让你的助手在会话中在身份之间切换:```bash
uvx zulipchat-mcp \
--zulip-config-file ~/.zuliprc \
--zulip-bot-config-file ~/.zuliprc-bot
助理职位如下 **你** 默认情况下。呼叫 `switch_identity` 以机器人身份发布——适用于自动通知、代理间通信,或保持人类与机器人消息的区别。
## 真实世界的例子
**“跟我聊聊今天#engineering发生了什么”**
→ 助理电话 `search_messages` 使用流+时间过滤器,总结线程。
**“告诉团队我们将在下午3点部署”**
→ 助理电话 `send_message` 以#engineering的名义宣布。
**“是谁发送了关于API迁移的消息?”**
→ 助理电话 `search_messages` 使用关键字,返回发件人和上下文。
**“使用:thumbs_up:响应Sarah的最后一条消息”**
→ 助理电话 `resolve_user` (“莎拉”), `search_messages` (发送者),那么 `add_reaction`.
**“DM Jaime,公关准备就绪”**
→ 助理电话 `teleport_chat` 具有模糊名称解析功能,无需电子邮件。
## 发展```bash
git clone https://github.com/akougkas/zulipchat-mcp.git
cd zulipchat-mcp
uv sync
uv run zulipchat-mcp --zulip-config-file ~/.zuliprc
运行检查:```bash
uv run pytest -q # full test suite, 60% coverage gate
uv run ruff check . # Linting
uv run mypy src # Type checking
对于打包、依赖关系、FastMCP或启动更改,请运行releasesmoke:```bash
uv build
scripts/pre_release_smoke.sh --version X.Y.Z --allow-dirty
看 贡献.md 获取完整指南,以及 CLAUDE.md / 代理商.md 获取AI代理指令。
建筑```
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 用于代理状态持久性,以及用于快速模糊解析的智能用户/流缓存。
隐私
- 无数据收集 -除了Zulip API调用之外,没有任何东西离开您的计算机
- 无遥测 --零分析、跟踪或使用报告
- 本地执行 --所有处理都发生在您的硬件上
- 凭证保留在本地 -API密钥不会被记录或传输到Zulip服务器之外
完整政策: 隐私.md
许可证
麻省理工学院——见 许可证
链接
- 文档索引
- 支持
- 安全策略
- Zulip API文档
- 模型上下文协议
- 报告问题
- 讨论
Built for the Zulip community
