禅道 MCP 服务器 - 助你高效管理项目
如何让 AI 助手直接访问你的禅道项目管理系统？本文介绍了一个基于 MCP 协议的创新解决方案，实现了 AI 与项目管理系统的无缝集成。
📌 前言
作为一名前端开发者，我每天都要在禅道项目管理系统中查看 Bug、跟进项目进度。在使用 AI 进行开发辅助时，我常常遇到这样一个痛点：
" 能帮我看看禅道里有哪些待处理的 Bug 吗？"
❌ "抱歉,我无法访问你的禅道系统..."
直到我发现了 MCP (Model Context Protocol) 协议,并基于此开发了 禅道 MCP 服务器，终于让 AI 能够直接访问禅道系统了！
😰 痛点：AI 助手的"信息孤岛"困境
在日常开发工作中,我们经常遇到以下场景：
1. 频繁的上下文切换
正在和 Claude 讨论代码实现
→ 需要查看 Bug 详情
→ 切换到浏览器打开禅道
→ 查找相关 Bug
→ 复制信息回到 Claude
→ 继续讨论...
这样的操作每天重复几十次，严重打断开发思路。
2. 信息传递效率低
- 需要手动复制 Bug 标题、描述、复现步骤等信息
- 无法让 AI 理解项目的整体 Bug 分布情况
- 每次查询都需要手动筛选和统计
3. 缺乏智能分析
- 无法让 AI 帮助分析 Bug 优先级
- 无法自动生成 Bug 报告
- 无法基于历史数据进行趋势分析
✨ 解决方案：基于 MCP 协议的禅道集成
什么是 MCP？
MCP (Model Context Protocol) 是 Anthropic 推出的开放标准协议，用于连接 AI 助手与外部系统。它定义了一套标准的工具（Tools）接口，让 AI 能够安全、高效地访问外部数据源。
项目架构
┌─────────────────┐ MCP 协议 ┌──────────────────┐
│ AI │ ──────────────────> │ 禅道 MCP 服务器 │
│ (AI 助手) │ │ (本项目) │
└─────────────────┘ └──────────────────┘
│
▼
┌──────────────────┐
│ 禅道 API │
│ (项目管理系统) │
└──────────────────┘
核心功能
本项目实现了 3 个核心 MCP 工具：
| 工具名称 | 功能描述 | 应用场景 |
|---|---|---|
zentao_list_projects | 查询项目列表 | 快速了解项目概况 |
zentao_list_bugs | 查询 Bug 列表（支持多维度过滤） | 精准定位目标 Bug |
zentao_get_bug_details | 获取 Bug 详情 | 深入分析 Bug 信息 |
技术亮点
1. 自动认证管理
class ZentaoClient {
private token: string | null = null;
private tokenExpiry: number = 0;
// Token 自动刷新机制
private async ensureAuthenticated(): Promise<void> {
if (!this.token || Date.now() >= this.tokenExpiry) {
await this.refreshToken();
}
}
}
- 支持 TTL 配置（默认 3600 秒）
- 自动检测 Token 过期并刷新
- 无需手动干预，透明处理认证逻辑
2. 强大的数据过滤能力
// 支持多维度 Bug 过滤
{
projectId: 1, // 指定项目
status: 'active', // 激活状态
severity: 'major', // 严重程度
priority: 'high', // 优先级
assignedTo: 'zhangsan', // 指派给谁
startDate: '2024-01-01', // 起始日期
endDate: '2024-12-31' // 截止日期
}
3. 双格式输出
- Markdown 格式：人类友好，适合直接展示
- JSON 格式：机器处理，适合数据分析和二次开发
4. 完善的错误处理
- 认证失败 → 清晰提示并引导检查配置
- 网络错误 → 自动重试机制
- 响应截断 → 25,000 字符保护限制
🚀 快速开始教程
方式一：使用 npm 包（推荐）
1. 安装并启动服务
npx @orange29233/zentao-mcp
2. 配置 AI
编辑 AI 配置文件：
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
添加以下配置：
{
"mcpServers": {
"zentao": {
"command": "npx",
"args": ["-y", "@orange29233/zentao-mcp"],
"env": {
"ZENTAO_URL": "https://your-zentao-domain.com",
"ZENTAO_USERNAME": "your-username",
"ZENTAO_PASSWORD": "your-password",
"ZENTAO_DEFAULT_PROJECT": "1"
}
}
}
}
3. 重启 AI
重启后，Claude 就能访问你的禅道数据了！
方式二：本地开发
1. 克隆项目
git clone https://github.com/orange29233/zentao-mcp.git
cd zentao-mcp
2. 安装依赖
npm install
3. 配置环境变量
cp .env.example .env
编辑 .env 文件：
ZENTAO_URL=https://your-zentao-domain.com
ZENTAO_USERNAME=your-username
ZENTAO_PASSWORD=your-password
ZENTAO_DEFAULT_PROJECT=1
TTL_SECONDS=3600
LOG_LEVEL=info
4. 编译并启动
npm run build # 编译 TypeScript
npm run dev # 开发模式（支持热重载）
💡 实战应用场景
场景 1：快速了解项目 Bug 状况
对话示例：
我：帮我看看禅道里有多少待处理的 Bug？
Claude：我帮你查询一下...
[使用 zentao_list_bugs 工具，过滤 status=active]
找到了 15 个激活状态的 Bug：
🔴 严重程度（3 个）
- #1234: 登录页面白屏 (major)
- #1235: 支付流程卡死 (critical)
- #1236: 数据丢失问题 (critical)
🟡 中等程度（8 个）
- #1237: 样式错位 (major)
- #1238: 按钮无响应 (major)
...
建议优先处理 2 个 critical 级别的 Bug。
场景 2：精准定位特定 Bug
对话示例：
我：找出指派给我的所有高优先级 Bug
Claude：好的，我来查询一下...
[使用 zentao_list_bugs 工具，设置 assignedTo='zhangsan', priority='high']
找到 5 个指派给你的高优先级 Bug：
1. #1240: 用户无法导出报表 (high, major)
2. #1241: 接口超时问题 (high, major)
...
需要我帮你分析哪个 Bug 应该先处理吗？
场景 3：深入分析 Bug 详情
对话示例：
我：详细分析一下 #1234 这个 Bug
Claude：我来获取详细信息...
[使用 zentao_get_bug_details 工具]
Bug #1234 详情：
- 标题：登录页面白屏
- 严重程度：major
- 状态：active
- 指派给：zhangsan
- 复现步骤：
1. 打开登录页面
2. 输入用户名密码
3. 点击登录按钮
4. 页面白屏，控制台报错：Uncaught TypeError...
分析：这是一个 JavaScript 错误导致的页面崩溃，建议检查登录按钮的点击事件处理逻辑。
需要我帮你生成修复代码吗？
场景 4：自动生成 Bug 报告
对话示例：
我：生成本周的 Bug 统计报告
Claude：我来收集数据并生成报告...
[使用 zentao_list_bugs 多次查询不同维度的数据]
## 本周 Bug 统计报告（2024.01.15 - 2024.01.21）
### 整体概况
- 新增 Bug：23 个
- 已解决：18 个
- 激活状态：15 个
### 严重程度分布
- Critical: 2 个 ⚠️
- Major: 8 个
- Minor: 10 个
- Trivial: 3 个
### 优先级分布
- High: 5 个
- Medium: 12 个
- Low: 6 个
### 待办建议
1. 优先处理 2 个 critical 级别的 Bug
2. 关注指派给 zhangsan 的 3 个 high 优先级 Bug
3. 建议安排代码审查以减少 minor 级别的 Bug
[完整报告已生成]
🎯 项目亮点总结
1. 开箱即用
- 支持
npx直接运行，无需克隆代码 - 详细的配置示例和环境变量模板
- 完善的错误提示和解决方案
2. 生产就绪
- TypeScript 类型安全
- 自动化测试和 CI/CD
- Token 缓存和自动刷新
- 响应截断保护
3. 开发友好
- 清晰的代码结构
- 详细的中文注释
- 完整的 API 文档
- 支持本地开发和调试
4. 性能优化
- Token 复用，减少认证请求
- 可配置的 TTL 缓存策略
- 响应大小限制保护
📊 实践效果
使用禅道 MCP 服务器后，我的工作流程发生了显著变化：
效率提升
- 减少上下文切换：从每天 20+ 次降低到 2-3 次
- 信息获取速度：从手动查询 2-3 分钟降低到对话式查询 10 秒
- 报告生成时间：从 30 分钟手动统计降低到自动生成 1 分钟
工作体验改善
- ✅ 不再频繁切换窗口
- ✅ AI 能理解项目整体情况
- ✅ 自动化生成分析报告
- ✅ 专注于代码实现，而非信息查询
🔧 技术栈
- Node.js 18+: 运行环境
- TypeScript: 类型安全
- MCP SDK: Anthropic 官方 SDK
- Zod: 运行时输入验证
- Axios: HTTP 请求
- Dotenv: 环境变量管理
📦 项目结构
zentao-mcp/
├── src/
│ ├── index.ts # MCP 服务器入口
│ ├── types.ts # TypeScript 类型定义
│ ├── constants.ts # 常量和枚举
│ ├── schemas/
│ │ └── tool-input-schemas.ts # Zod 验证 Schema
│ ├── services/
│ │ └── zentao-client.ts # 禅道 API 客户端
│ └── tools/
│ ├── projects.ts # 项目查询工具
│ └── bugs.ts # Bug 查询工具
├── package.json
├── tsconfig.json
├── README.md # 详细文档
└── .env.example # 配置示例
🎓 进阶使用技巧
1. 自定义默认项目
在环境变量中设置 ZENTAO_DEFAULT_PROJECT，避免每次都指定项目 ID。
2. 调整 Token 缓存时间
根据禅道服务器的 Token 策略，调整 TTL_SECONDS 以优化性能。
3. 日志级别控制
设置 LOG_LEVEL 为 debug 可以看到详细的请求日志，方便排查问题。
4. 结合其他 MCP 工具
可以同时使用多个 MCP 服务器（如 GitHub、Jira），构建完整的 AI 开发助手。
🤝 贡献指南
欢迎提交 Issue 和 Pull Request！
📝 总结
禅道 MCP 服务器通过标准化的 MCP 协议，成功将 AI 助手与项目管理系统连接起来，解决了开发者在使用 AI 辅助编程时的"信息孤岛"问题。
核心价值：
- 🚀 提升工作效率：减少 80% 的信息查询时间
- 🤝 增强协作能力：AI 能理解项目整体状况
- 📊 数据驱动决策：自动生成分析报告
- 🔧 易于集成：开箱即用，配置简单
如果你也在使用禅道进行项目管理，强烈建议尝试一下这个工具，让 AI 成为你的项目管理助手！
项目地址: @orange29233/zentao-mcp
NPM 包: @orange29233/zentao-mcp
作者: orange29233
许可: MIT
💡 推荐阅读:
如果这篇文章对你有帮助，欢迎点赞、收藏、评论！有任何问题也欢迎在评论区讨论。
