内容
# Zulip MCP 服务器
一款 Model Context Protocol (MCP) 服务器，暴露 Zulip REST API 功能，作为 LLM 的工具。该服务器允许 AI 助手以编程方式与您的 Zulip 工作空间交互。
## 功能
### 🔄 **资源** (上下文数据)
- **用户目录**：浏览具有角色和状态的组织成员
- **流目录**：探索可用的流和权限
- **消息格式化指南**：完整的 Zulip Markdown 语法参考
- **组织信息**：服务器设置、策略和自定义表情符号
- **用户组**：用于提及和权限的可用组
### 🛠️ **工具** (25 个可用操作)
#### 辅助工具 (LLM 友好发现)
- `search-users` - 在发送直接消息之前按姓名/电子邮件查找用户
- `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 术语：流 vs 通道
在 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. **克隆并安装依赖项：**
```bash
git clone <仓库网址>
cd zulip-mcp-server
npm install
```
2. **配置环境变量：**
```bash
cp .env.example .env
# 使用您的 Zulip 凭证编辑 .env
```
3. **构建和运行：**
```bash
npm run build
npm start
```
### 环境配置
使用您的 Zulip 凭证创建 `.env` 文件：
```env
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. **机器人访问** （推荐）：
- 进入您的 Zulip 组织设置
- 导航到“机器人”部分
- 创建新机器人或使用现有机器人
- 复制机器人电子邮件和 API 密钥
2. **个人访问**：
- 进入个人设置 → 账户和隐私
- 找到“API 密钥”部分
- 生成或显示您的 API 密钥
### Claude 桌面集成
要将此 MCP 服务器与 Claude 桌面一起使用，请在 Claude 桌面配置文件中添加以下配置：
#### 选项 1：使用环境变量（推荐）
添加到您的 Claude 桌面配置中：
```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"
}
}
}
}
```
#### 选项 2：使用 .env 文件
如果您更喜欢使用 `.env` 文件，请确保它位于项目目录中，并使用：
```json
{
"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`
- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
### Cursor 集成
要将此 MCP 服务器与 Cursor IDE 一起使用，请在 Cursor MCP 设置中添加以下内容：
#### Cursor MCP 配置
添加到 Cursor 的 MCP 设置文件（`.cursor-mcp/config.json` 在您的工作区或全局设置中）：
```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
}
}
}
}
```
**Cursor MCP 配置位置：**
- **工作区**：项目根目录中的 `.cursor-mcp/config.json`
- **全局**：Cursor 特定的平台设置目录
### Raycast MCP 扩展
要将此 MCP 服务器与 Raycast 一起使用，请在 MCP 扩展设置中进行配置：
#### Raycast MCP 配置
添加到 Raycast MCP 扩展配置中：
```json
{
"servers": {
"zulip": {
"name": "Zulip 集成",
"description": "发送消息和与 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"
},
"icon": "💬",
"categories": ["communication", "productivity"]
}
}
}
```
**Raycast 设置步骤：**
1. 安装 Raycast MCP 扩展
2. 打开 Raycast 首选项 → 扩展 → MCP
3. 添加新的服务器配置
4. 粘贴上面的 JSON 配置
5. 更新路径和凭证
**Raycast 使用方法：**
- 使用 `⌘ + Space` 打开 Raycast
- 搜索“Zulip”命令
- 直接从 Raycast 界面执行 MCP 工具
### 支持的 MCP 客户端
此服务器与任何符合 MCP 的客户端兼容。以下是已验证的集成：
| 平台 | 配置类型 | 状态 | 用例 |
|----------|-------------|---------|-------|
| **Claude 桌面** | JSON 配置 | ✅ 已验证 | 与 Zulip 集成进行 AI 对话 |
| **Cursor IDE** | 工作区/全局配置 | ✅ 已验证 | 具有 Zulip 通知的代码编辑器 |
| **Raycast** | 扩展配置 | ✅ 已验证 | 快速命令和自动化 |
| **其他 MCP 客户端** | 标准 MCP 协议 | 🔄 兼容 | 任何符合 MCP 的应用程序 |
**通用 MCP 命令：**
```bash
node /path/to/zulip-mcp-server/dist/server.js
```
## 开发
### 脚本
```bash
npm run dev # 开发环境，随时重新加载
npm run build # 构建生产环境
npm test # 运行测试
npm run lint # 检查 TypeScript
npm run typecheck # 类型检查
```
### 项目结构
```
src/
├── server.ts # 主要的 MCP 服务器
├── zulip/
│ └── client.ts # Zulip API 客户端
└── types.ts # TypeScript 定义
```
### 测试
使用 MCP 检测器测试服务器：
```bash
npx @modelcontextprotocol/inspector npm start
```
## 使用示例
### 发送消息
```typescript
// 发送到流
await callTool("send-message", {
type: "stream",
to: "general",
topic: "每日站会",
content: "早上好，团队！ 👋\n\n**今日目标：**\n- 审查 PR #123\n- 部署功能 X"
});
// 直接消息
await callTool("send-message", {
type: "direct",
to: "user@example.com",
content: "嘿！您有时间时可以查看最新的更改吗？"
});
```
### 获取消息
```typescript
// 从流中获取最近的消息
await callTool("get-messages", {
narrow: [["stream", "general"], ["topic", "announcements"]],
num_before: 50
});
// 搜索消息
await callTool("get-messages", {
narrow: [["search", "deployment"], ["sender", "admin@example.com"]]
});
```
### 流管理
```typescript
// 列出已订阅的流
await callTool("get-subscribed-streams", {
include_subscribers: true
});
// 获取流主题
await callTool("get-topics-in-stream", {
stream_id: 123
});
```
## Markdown 格式化支持
服务器包含一个全面的格式化指南资源。Zulip 支持：
- **标准 Markdown**：粗体、斜体、代码、链接、列表
- **提及**：`@**完整姓名**` （通知），`@_**姓名**_` （静默）
- **流链接**：`#**流名称**`
- **代码块**：具有语法高亮
- **数学**：使用 `$$数学$$` 的 LaTeX 表达式
- **隐藏内容**：`||隐藏内容||`
- **自定义表情符号**：组织特定的表情符号
## 错误处理
服务器提供全面的错误处理：
- 网络连接问题
- 身份验证失败
- 权限错误
- 速率限制
- 无效参数
- Zulip API 错误
所有错误都包含有用的调试信息。
## 贡献
1. 复刻仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保 TypeScript 编译通过
5. 提交拉取请求
## 支持
如有问题和疑问：
- 查看 Zulip API 文档：https://zulip.com/api/
- 查看 MCP 规范：https://modelcontextprotocol.io/
- 为错误或功能请求打开 GitHub 问题
MCP 市场
