Zulip MCP Server

Zulip MCP 服务

一个 Model Context Protocol（MCP）服务，可将 Zulip REST API 功能作为工具提供给大模型。此服务允许 AI 助手通过编程方式与您的 Zulip 工作区交互。

功能

🔄 资源（上下文数据）

• 用户目录：浏览组织成员及其角色和状态
• Stream 目录：查看可用的 stream 和权限
• 消息格式指南：完整的 Zulip Markdown 语法参考
• 组织信息：服务设置、策略和自定义表情符号
• 用户组：可用于提及和权限设置的群组

🛠️ 工具（25 项可用操作）

辅助工具（便于大模型发现）

• search-users - 发送私信前，按姓名或电子邮件查找用户
• get-started - 测试连接并获取工作区概览

消息操作

• send-message - 向 stream 或私信发送消息
• get-messages - 使用高级筛选和搜索获取消息
• get-message - 获取特定消息的详细信息
• upload-file - 分享文件和图片
• edit-message - 修改内容或移动主题
• delete-message - 删除消息（需要管理员权限）
• get-message-read-receipts - 查看谁已读消息
• add-emoji-reaction - 使用 Unicode 或自定义表情符号回应
• remove-emoji-reaction - 移除消息上的表情符号回应

定时消息和草稿

• create-scheduled-message - 定时发送未来的消息
• edit-scheduled-message - 修改定时消息
• create-draft - 创建新的消息草稿
• get-drafts - 获取已保存的草稿
• edit-draft - 更新草稿内容

Stream 管理

• get-subscribed-streams - 列出用户订阅的 stream
• get-stream-id - 按名称获取 stream ID
• get-stream-by-id - 获取 stream 的详细信息
• get-topics-in-stream - 浏览最近的主题

用户操作

• get-users - 列出组织成员
• get-user-by-email - 按电子邮件查找用户
• get-user - 按 ID 获取用户详细信息
• update-status - 设置状态消息和在线状态
• get-user-groups - 列出可用的用户组

📝 Zulip 术语：Streams 与 Channels

在 Zulip 中，“streams” 和 “channels” 指的是同一概念：

• Stream = Zulip 的官方术语（用于 API、工具和界面）
• Channel = Slack/Discord/Teams 中的常见术语
• 含义相同 = 团队讨论各类主题的对话空间

此 MCP 服务使用 “stream”，以符合 Zulip 的官方文档和 API。

安装与设置

前置条件

• Node.js 18+ 和 npm
• TypeScript 5+
• 可访问 Zulip 实例（例如，https://your-organization.zulipchat.com）
• Zulip API 凭据（机器人令牌或 API 密钥）

快速开始

1. 克隆并安装依赖项：

git clone <repository-url>
cd zulip-mcp-server
npm install

2. 配置环境变量：

cp .env.example .env
# Edit .env with your Zulip credentials

3. 构建并运行：

npm run build
npm start

环境配置

创建包含 Zulip 凭据的 .env 文件：

ZULIP_URL=https://your-organization.zulipchat.com
[email protected]
ZULIP_API_KEY=your-api-key-here
NODE_ENV=production

获取 Zulip API 凭据

1. 用于机器人访问（推荐）：

   • 前往 Zulip 组织设置
   • 导航到 “Bots” 部分
   • 创建新机器人或使用现有机器人
   • 复制机器人电子邮件和 API 密钥

2. 用于个人访问：

   • 前往个人设置 → 账户与隐私
   • 找到 “API key” 部分
   • 生成或显示 API 密钥

Claude Desktop 集成

若要将此 MCP 服务与 Claude Desktop 配合使用，请将以下配置添加到 Claude Desktop 配置文件中：

选项 1：使用环境变量（推荐）

添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "env": {
        "ZULIP_URL": "https://your-organization.zulipchat.com",
        "ZULIP_EMAIL": "[email protected]", 
        "ZULIP_API_KEY": "your-api-key-here"
      }
    }
  }
}

选项 2：使用 .env 文件

如果您倾向于使用 .env 文件，请确保文件位于项目目录中，并使用：

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "cwd": "/path/to/zulip-mcp-server"
    }
  }
}

Claude Desktop 配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

Cursor 集成

若要将此 MCP 服务与 Cursor IDE 配合使用，请将以下内容添加到 Cursor MCP 设置中：

Cursor MCP 配置

添加到 Cursor 的 MCP 设置文件（工作区中的 .cursor-mcp/config.json 或全局设置）：

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "env": {
        "ZULIP_URL": "https://your-organization.zulipchat.com",
        "ZULIP_EMAIL": "[email protected]",
        "ZULIP_API_KEY": "your-api-key-here"
      },
      "capabilities": {
        "tools": true,
        "resources": true
      }
    }
  }
}

Cursor MCP 配置位置：

• 工作区：项目根目录中的 .cursor-mcp/config.json
• 全局：特定平台的 Cursor 设置目录

Raycast MCP 扩展

要在 Raycast 中使用此 MCP 服务，请在 MCP 扩展设置中进行配置：

Raycast MCP 配置

添加到 Raycast MCP 扩展配置中：

{
  "servers": {
    "zulip": {
      "name": "Zulip Integration",
      "description": "Send messages and interact with Zulip workspace",
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "env": {
        "ZULIP_URL": "https://your-organization.zulipchat.com",
        "ZULIP_EMAIL": "[email protected]",
        "ZULIP_API_KEY": "your-api-key-here"
      },
      "icon": "💬",
      "categories": ["communication", "productivity"]
    }
  }
}

Raycast 设置步骤：

1. 安装 Raycast MCP 扩展
2. 打开 Raycast 偏好设置 → 扩展 → MCP
3. 添加新的服务配置
4. 粘贴上面的 JSON 配置
5. 相应地更新路径和凭据

Raycast 使用方法：

• 使用 ⌘ + Space 打开 Raycast
• 搜索“Zulip”命令
• 直接从 Raycast 界面执行 MCP 工具

支持的 MCP 客户端

此服务兼容任何符合 MCP 规范的客户端。以下是已验证的集成：

平台	配置类型	状态	用途
Claude Desktop	JSON 配置	✅ 已验证	集成 Zulip 的 AI 对话
Cursor IDE	工作区/全局配置	✅ 已验证	带有 Zulip 通知的代码编辑器
Raycast	扩展配置	✅ 已验证	快捷命令和自动化
其他 MCP 客户端	标准 MCP 协议	🔄 兼容	任何符合 MCP 规范的应用程序

通用 MCP 命令：

node /path/to/zulip-mcp-server/dist/server.js

开发

脚本

npm run dev          # Development with hot reload
npm run build        # Build for production
npm test            # Run tests
npm run lint        # Lint TypeScript
npm run typecheck   # Type checking

项目结构

src/
├── server.ts        # Main MCP server
├── zulip/
│   └── client.ts    # Zulip API client
└── types.ts         # TypeScript definitions

测试

使用 MCP Inspector 测试服务：

npx @modelcontextprotocol/inspector npm start

使用示例

发送消息

// Send to a stream
await callTool("send-message", {
  type: "stream",
  to: "general",
  topic: "Daily Standup",
  content: "Good morning team! 👋\n\n**Today's Goals:**\n- Review PR #123\n- Deploy feature X"
});

// Direct message
await callTool("send-message", {
  type: "direct",
  to: "[email protected]",
  content: "Hey! Can you review the latest changes when you have a moment?"
});

获取消息

// Get recent messages from a stream
await callTool("get-messages", {
  narrow: [["stream", "general"], ["topic", "announcements"]],
  num_before: 50
});

// Search messages
await callTool("get-messages", {
  narrow: [["search", "deployment"], ["sender", "[email protected]"]]
});

流管理

// List subscribed streams
await callTool("get-subscribed-streams", {
  include_subscribers: true
});

// Get stream topics
await callTool("get-topics-in-stream", {
  stream_id: 123
});

Markdown 格式支持

该服务包含全面的格式指南资源。Zulip 支持：

• 标准 Markdown：粗体、斜体、代码、链接、列表
• 提及：@**Full Name**（通知）、@_**Name**_（静默）
• 流链接：#**stream-name**
• 代码块：支持语法高亮
• 数学公式：使用 $$math$$ 编写 LaTeX 表达式
• 剧透内容：||hidden content||
• 自定义表情符号：组织专属表情符号

错误处理

该服务提供全面的错误处理：

• 网络连接问题
• 身份验证失败
• 权限错误
• 速率限制
• 无效参数
• Zulip API 错误

所有错误都包含有助于调试的提示信息。

贡献

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保 TypeScript 编译通过
5. 提交 pull request

支持

如有问题或疑问：

• 查看 Zulip API 文档：https://zulip.com/api/
• 查看 MCP 规范：https://modelcontextprotocol.io/
• 在 GitHub 上提交 Bug 或功能请求