Zulip MCP Server

Zulip MCP服务器

一个模型上下文协议（MCP）服务器，它公开Zulip REST API功能作为LLM的工具。此服务器允许AI助手以编程方式与您的Zulip工作区进行交互。

特性

🔄 资源 （上下文数据）

• 用户目录：浏览具有角色和状态的组织成员
• 流目录：探索可用流和权限
• 邮件格式指南：完整的Zulip markdown语法参考
• 组织信息：服务器设置、策略和自定义表情符号
• 用户组：可用于提及和权限的组

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

辅助工具（LLM友好发现）

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

消息操作

• send-message -发送到流媒体或直接消息
• 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 -更新草稿内容

流管理

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

用户操作

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

📝 Zulip术语：流与通道

在Zulip， “流” 和 “频道” 参考相同的概念：

• 流 =Zulip官方术语（用于API、工具、界面）
• 频道 =来自Slack/Discord/Teams的常用术语
• 同样的事情 =团队讨论主题的对话空间

此MCP服务器使用“流”来匹配Zulip的官方文档和API。

安装和设置

先决条件

• Node.js 18+与npm
• TypeScript 5+
• 访问Zulip实例（例如。，https://your-organization.zulipchat.com)
• Zulip API证书（机器人程序令牌或API密钥）

快速开始

1. 克隆和安装依赖关系：

git clone 
cd zulip-mcp-server
npm install

1. 配置环境变量：

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

1. 构建并运行：

npm run build
npm start

环境配置

创建一个 .env 使用您的Zulip凭据文件：

ZULIP_URL=https://your-organization.zulipchat.com
ZULIP_EMAIL=your-bot-email@yourcompany.com
ZULIP_API_KEY=your-api-key-here
NODE_ENV=production

获取Zulip API证书

1. 用于Bot访问 （推荐）：

- 转到您的Zulip组织设置 - 导航到“机器人”部分 - 创建新的机器人或使用现有的机器人 - 复制机器人程序电子邮件和API密钥

1. 用于个人访问:

- 转到个人设置→ 帐户和隐私 - 查找“API密钥”部分 - 生成或显示您的API密钥

Claude桌面集成

要将此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": "your-bot-email@yourcompany.com", 
        "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桌面配置位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

光标集成

要将此MCP服务器与Cursor IDE一起使用，请在Cursor MCP设置中添加以下内容：

光标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": "your-bot-email@yourcompany.com",
        "ZULIP_API_KEY": "your-api-key-here"
      },
      "capabilities": {
        "tools": true,
        "resources": true
      }
    }
  }
}

光标MCP配置位置：

• 工作区: .cursor-mcp/config.json 在项目根目录中
• 全球：特定于平台的游标设置目录

Raycast MCP扩展

要将此MCP服务器与Raycast一起使用，请在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": "your-bot-email@yourcompany.com",
        "ZULIP_API_KEY": "your-api-key-here"
      },
      "icon": "💬",
      "categories": ["communication", "productivity"]
    }
  }
}

光线投射设置步骤：

1. 安装Raycast MCP扩展
2. 打开“光线投射”首选项→ 扩展→ MCP
3. 添加新的服务器配置
4. 粘贴上面的JSON配置
5. 相应地更新路径和凭据

Raycast用法：

• 使用 ⌘ + Space 打开Raycast
• 搜索“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检查器测试服务器：

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: "user@example.com",
  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", "admin@example.com"]]
});

流管理

// 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**
• 代码块：带有语法高亮显示
• 数学：LaTeX表达式 $$math$$
• 剧透: ||hidden content||
• 自定义表情符号：特定于组织的表情符号

错误处理

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

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

所有错误都包含有助于调试的消息。

贡献

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保TypeScript编译通过
5. 提交拉取请求

支持

对于问题和疑问：

• 查看Zulip API文档：https://zulip.com/api/
• 审查MCP规范：https://modelcontextprotocol.io/
• 打开GitHub问题以查找错误或功能请求