Taiga Mcp Server

🚀 Taiga MCP 服务

一个功能强大的 Model Context Protocol（MCP） 服务，支持通过自然语言与 Taiga 项目管理系统交互。通过对话式 AI，无缝管理项目、迭代、用户故事、任务和问题。

🤖 AI 驱动的开发：本项目由 Claude Code（claude.ai/code）协作开发，展现了 AI 辅助软件开发的潜力。

✨ 功能

📊 完整的项目管理

• 项目：列出项目并查看项目详情
• 迭代：创建、列出迭代并跟踪进度，同时查看详细统计数据
• 用户故事：在项目中创建和管理用户故事
• 任务：创建与用户故事关联的任务
• 问题：全面管理问题的生命周期及其与迭代的关联

🔗 高级迭代-问题跟踪

• 按迭代查看问题，并显示完整的关联关系
• 获取详细的问题信息，包括迭代分配情况
• 通过完成统计数据跟踪迭代进度
• 实时更新状态并监控进度

🚀 批量操作

• 批量创建问题：一次操作创建多个问题（最多 20 个）
• 批量创建用户故事：批量创建带有故事点的用户故事
• 批量创建任务：为指定用户故事批量创建任务
• 智能错误处理：单个项目失败不会影响其他项目
• 详细报告：显示每个项目的成功或失败状态

🔍 高级查询语法

• 类 SQL 查询语言：使用 field:operator:value 语法进行精确搜索
• 逻辑运算符：使用 AND、OR、NOT 组合条件
• 文本匹配：支持模糊搜索、通配符和子字符串匹配
• 日期范围：灵活的基于时间的查询（today、last_week、>7d）
• 排序与限制：使用 ORDER BY 和 LIMIT 子句控制结果

💬 团队协作系统

• 评论管理：为任意工作项添加、查看、编辑和删除评论
• 讨论串：查看包含用户信息的完整评论历史
• 团队沟通：通过结构化讨论加强协作
• 实时更新：在团队成员之间即时同步评论

📎 文件附件管理

• 灵活的文件上传：支持通过文件路径和 Base64 上传
• Claude 客户端集成：针对 Claude Desktop 文件处理进行优化
• 多格式支持：支持图像、文档、PDF 和所有主流文件类型
• 智能路径解析：自动从常见位置检测文件路径
• 下载管理：高效下载文件并管理路径
• 存储整理：通过描述清晰地管理附件

🏛️ Epic 管理（企业级）

• 大规模组织：创建和管理 Epic 级别的项目组件
• 分层结构：将用户故事关联到 Epic，以全面了解项目
• 进度跟踪：跟踪 Epic 级别的进度统计数据和完成情况
• 企业规划：支持路线图规划和功能发布

📖 Wiki 管理（知识库）

• 文档中心：创建和管理项目 Wiki 页面，以共享知识
• Markdown 支持：全面支持 Markdown 编辑和丰富的内容格式
• 灵活的标识方式：通过 ID 或易于使用的 slug 名称访问页面
• 协作功能：关注或取消关注页面，以接收更改通知
• 版本控制：自动进行版本管理，防止编辑冲突
• 内容组织：集中管理各项目的文档

💬 自然语言界面

• “列出所有项目”
• “显示 Sprint 5 的进度统计信息”
• “在项目 X 中创建一个高优先级缺陷问题”
• “Sprint 3 中分配了哪些问题？”
• “获取问题 #123 的详细信息”

🛠️ 安装与设置

前置条件

• Node.js（v14 或更高版本）- 在此下载
• Taiga 账户，并拥有 API 访问权限

选项 1：NPX（推荐）

无需安装——自动运行最新版本：

# NPM Registry (official)
npx taiga-mcp-server

# GitHub Package Registry (alternative)
npx @greddy7574/taiga-mcp-server

选项 2：全局安装

# From NPM Registry
npm install -g taiga-mcp-server
taiga-mcp

# From GitHub Packages
npm install -g @greddy7574/taiga-mcp-server

选项 3：Docker 部署

# Build the image
docker build -t taiga-mcp-server .

# Run with environment file
docker run --rm -i --env-file .env taiga-mcp-server

# Or with environment variables
docker run --rm -i \
  -e TAIGA_API_URL=https://api.taiga.io/api/v1 \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  taiga-mcp-server

# Using docker-compose
docker-compose up --build

⚙️ 配置

Claude Desktop 集成

NPX 方式（推荐）

将以下内容添加到 Claude Desktop 的 config.json：

{
  "mcpServers": {
    "taiga-mcp": {
      "command": "npx",
      "args": ["taiga-mcp-server"],
      "env": {
        "TAIGA_API_URL": "https://api.taiga.io/api/v1",
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Docker 方式

{
  "mcpServers": {
    "taiga-mcp": {
      "command": "docker",
      "args": [
        "run", 
        "--rm", 
        "-i",
        "-e", "TAIGA_API_URL=https://api.taiga.io/api/v1",
        "-e", "TAIGA_USERNAME=your_username",
        "-e", "TAIGA_PASSWORD=your_password",
        "taiga-mcp-server:latest"
      ]
    }
  }
}

Docker Compose 方式

{
  "mcpServers": {
    "taiga-mcp": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/project/docker-compose.yml",
        "run", "--rm", "taiga-mcp-server"
      ],
      "cwd": "/path/to/project"
    }
  }
}

自定义 Taiga 实例

适用于可自托管的 Taiga 实例：

{
  "env": {
    "TAIGA_API_URL": "https://your-taiga-domain.com/api/v1",
    "TAIGA_USERNAME": "your_username",
    "TAIGA_PASSWORD": "your_password"
  }
}

🎯 使用示例

Sprint 管理

🗣️ "Show me all sprints in project MyApp"
📊 Returns: List of sprints with status and dates

🗣️ "Get details for Sprint 5"
🔍 Returns: Complete sprint information including:
   - Basic info (ID, slug, status, order)
   - Timeline (start/end dates, created/modified dates)
   - Metrics (total/closed points, user story count)
   - Team (owner, watchers, available roles)
   - Description and user stories list
   - Full JSON data for programmatic access

🗣️ "Get detailed statistics for Sprint 5"
📈 Returns: Progress stats, completion rates, user stories count

🗣️ "Create a new sprint called 'Q1 Release' from 2024-01-01 to 2024-03-31"
✅ Returns: Created sprint details

问题跟踪

🗣️ "List all issues in project MyApp"
📋 Returns: Issues with sprint assignments and status

🗣️ "Show me issue #123 details"
🔍 Returns: Complete issue info including sprint, assignee, timeline

🗣️ "Update issue 838 status to 'In Progress'"
🔄 Returns: Issue status updated with confirmation

🗣️ "Assign issue 838 to John Doe"
👤 Returns: Issue assigned to team member with details

🗣️ "Add issue 838 to Sprint 1.0.95"
🏃 Returns: Issue moved to sprint with confirmation

🗣️ "Remove issue 838 from sprint"
🏃 Returns: Issue removed from sprint assignment

🗣️ "What issues are in Sprint 3?"
📋 Returns: All issues assigned to that sprint

项目管理

🗣️ "Create a high-priority bug issue: 'Login page not working'"
🐛 Returns: Created issue with details

🗣️ "List all user stories in project MyApp"
📝 Returns: User stories with status and assignments

🗣️ "Show me user story #456 details"
🔍 Returns: Complete user story info including project, status, and points

🗣️ "Assign user story 456 to sprint 101"
🏃 Returns: User story assigned to sprint with confirmation

🗣️ "Unassign user story 456 from sprint"
🏃 Returns: User story removed from sprint assignment

🗣️ "Create these 5 issues in batch: Bug1, Bug2, Feature1, Task1, Task2"
🚀 Returns: Batch creation results with individual success/failure status

批量操作示例

🗣️ "Batch create these issues in MyApp:
- Bug: Login page broken (High priority)
- Feature: Add search functionality (Medium priority) 
- Task: Update documentation (Low priority)"
📊 Returns: Created 3/3 issues successfully with reference numbers

🗣️ "Batch create user stories:
- User registration flow (5 points)
- Password reset feature (3 points)
- Email notifications (2 points)"
📋 Returns: Created 3/3 user stories with story point assignments

高级查询示例

🗣️ "Find all high priority bugs assigned to john: status:open AND priority:high AND assignee:john AND type:bug"
📊 Returns: Filtered list of critical bugs needing attention

🗣️ "Show user stories with 5+ points created this week: points:>=5 AND created:this_week ORDER BY points DESC"
📈 Returns: High-value stories with detailed point breakdown

🗣️ "Search for API-related tasks: subject:contains:\"API\" OR description:contains:\"API\" LIMIT 10"
🔍 Returns: All tasks mentioning API with relevance ranking

评论系统示例

🗣️ "Add comment to issue #123: 'This needs more testing before deployment'"
💬 Returns: Comment added successfully with timestamp and user info

🗣️ "Show me all comments for user story #456"
📝 Returns: Complete comment history with user names and dates

🗣️ "Edit comment #789 to say 'Updated implementation approach'"
✏️ Returns: Comment updated successfully with new content

🗣️ "Delete comment #321"
🗑️ Returns: Comment removed from the discussion thread

文件附件示例

🗣️ "Upload design.pdf to user story #456 with description 'UI mockup v2'"
📎 Returns: File uploaded successfully with size and metadata

🗣️ "Upload screenshot.png to issue #123 in project MyApp"
📸 Returns: Image file attached with automatic MIME type detection

🗣️ "List all attachments for issue #789"
📂 Returns: Complete attachment list with filenames, sizes, and upload dates

🗣️ "Download attachment #123 to /Downloads/documents/"
⬇️ Returns: File downloaded successfully to specified location

🗣️ "Delete attachment #456"
🗑️ Returns: Attachment removed from the project

文件上传方式

系统支持两种上传方式，可针对不同用例进行优化：

方式 1：文件路径（推荐用于 Claude Desktop）

{
  "itemType": "issue",
  "itemId": 123,
  "projectIdentifier": "MyApp",
  "filePath": "design.pdf",
  "description": "UI mockup v2"
}

方式 2：Base64 数据（用于编程调用）

{
  "itemType": "issue", 
  "itemId": 123,
  "projectIdentifier": "MyApp",
  "fileData": "base64_encoded_file_content",
  "fileName": "design.pdf",
  "mimeType": "application/pdf",
  "description": "UI mockup v2"
}

Epic 管理示例

🗣️ "Create epic 'API v2.0 Migration' in project MyApp with description 'Complete API redesign'"
🏛️ Returns: Epic created with ID, color, and project association

🗣️ "List all epics in project MyApp"
📋 Returns: Epic list with progress stats and linked user stories count

🗣️ "Get details for epic #789"
📊 Returns: Epic overview with progress, status, and linked user stories

🗣️ "Link user story #456 to epic #789"
🔗 Returns: Story successfully linked to epic for better organization

🗣️ "Update epic #789 status to 'In Progress' and add tag 'backend'"
✏️ Returns: Epic updated with new status and organizational tags

Wiki 管理示例

🗣️ "Create wiki page 'api-documentation' in project MyApp with content about API usage"
📖 Returns: Wiki page created with slug, project association, and content preview

🗣️ "List all wiki pages in project MyApp"
📋 Returns: Complete wiki page list with modification dates and content summaries

🗣️ "Get wiki page 'user-guide' details from project MyApp"
🔍 Returns: Full wiki content, metadata, watchers, and version information

🗣️ "Update wiki page 'installation-guide' with new Docker instructions"
✏️ Returns: Wiki page updated with new content and incremented version

🗣️ "Watch wiki page 'api-documentation' for change notifications"
👁️ Returns: Successfully subscribed to wiki page change notifications

🗣️ "Delete wiki page 'outdated-info' from project MyApp"
🗑️ Returns: Wiki page permanently deleted with confirmation details

🔧 可用工具（共 42 个）

🔐 身份验证（1 个工具）

工具	描述
authenticate	使用 Taiga API 进行身份验证

📁 项目管理（2 个工具）

工具	描述
listProjects	获取所有可访问的项目
getProject	查看项目详细信息

🏃 Sprint 管理（5 个工具）

工具	描述
listMilestones	列出项目中的所有 Sprint
getMilestone	获取完整的 Sprint 详情，包括用户故事、关注者、负责人、时间线、指标和完整 JSON 数据
getMilestoneStats	获取 Sprint 进度和统计信息
createMilestone	创建带日期的新 Sprint
getIssuesByMilestone	查看 Sprint 中的所有问题

🐛 问题管理（6 个工具）

工具	描述
listIssues	列出问题及 Sprint 信息
getIssue	获取问题详细信息
createIssue	创建问题并设置优先级/类型
updateIssueStatus	更新问题状态（例如，“进行中”、“已完成”）
addIssueToSprint	将问题分配到 Sprint，或从 Sprint 中移除
assignIssue	将问题分配给团队成员，或取消分配

📝 用户故事管理（4 个工具）

工具	描述
listUserStories	查看项目中的用户故事
getUserStory	获取用户故事详细信息
createUserStory	创建新的用户故事
assignUserStoryToSprint	将用户故事分配到 Sprint，或取消分配

✅ 任务管理（1 个工具）

工具	描述
createTask	创建与用户故事关联的任务

🚀 批量操作（3 个工具）

工具	描述
batchCreateIssues	批量创建多个问题（最多 20 个）
batchCreateUserStories	批量创建多个用户故事
batchCreateTasks	为一个用户故事批量创建多个任务

🔍 高级搜索（3 个工具）

工具	描述
advancedSearch	执行类似 SQL 的高级查询
queryHelp	获取查询语法帮助和示例
validateQuery	在执行前验证查询语法

💬 评论系统（4 个工具）

工具	描述
addComment	为问题、故事或任务添加评论
listComments	查看条目的评论历史
editComment	编辑现有评论
deleteComment	删除评论

📎 文件附件（4 个工具）

工具	描述	主要功能
uploadAttachment	将文件上传到问题、故事或任务	支持两种方式（文件路径/Base64）、智能路径解析
listAttachments	查看项目的附件列表	提供包含文件大小和上传日期的完整元数据
downloadAttachment	按 ID 下载附件	灵活管理下载路径
deleteAttachment	删除附件	安全删除并提供确认

🏛️ Epic 管理（6 个工具）

工具	描述
createEpic	创建大型 Epic 功能
listEpics	列出项目中的所有 Epic
getEpic	获取 Epic 详情和进度统计
updateEpic	更新 Epic 信息和状态
linkStoryToEpic	将用户故事关联到 Epic
unlinkStoryFromEpic	移除故事与 Epic 的关联

📖 Wiki 管理（6 个工具）

工具	描述
createWikiPage	创建支持 Markdown 的项目 Wiki 页面
listWikiPages	列出项目中的所有 Wiki 页面
getWikiPage	按 ID 或 slug 获取 Wiki 页面详情
updateWikiPage	更新 Wiki 页面内容和设置
deleteWikiPage	删除 Wiki 页面（不可撤销）
watchWikiPage	关注/取消关注 Wiki 页面以接收通知

🚀 为什么选择 Taiga MCP Server？

• 🔥 零配置：使用 npx 即可立即运行
• 🧠 原生适配 AI：专为对话式项目管理打造
• 🔗 完整集成：全面覆盖 Taiga API，包含 39 个工具
• 📊 丰富数据：详细的进度跟踪和统计信息
• 🎯 专注 Sprint：高级 Sprint 与问题关系跟踪
• 🛡️ 安全可靠：基于环境变量管理凭据
• 🚀 批量操作：为大型项目提供高效的批量操作
• 💬 团队协作：完整的评论系统，助力高效沟通
• 📎 文件管理：支持两种上传方式（文件路径/Base64），并针对 Claude Desktop 进行了优化
• 🏛️ 企业就绪：通过 Epic 管理大型项目组织
• 📖 知识管理：完整的 Wiki 系统，用于项目文档管理
• 🔍 高级搜索：使用类 SQL 查询语法进行复杂数据筛选

🙏 致谢

署名和法律声明

本项目受 adriapedralbes 的 mcpTAIGA 启发。此版本经过大幅重写和重新实现，采用了全新的架构、功能和特性，同时沿用相同的 ISC 许可条款。

AI 辅助开发

🤖 使用 Claude Code 开发：本项目完全通过与 Claude Code 协作开发，展示了 AI 辅助软件开发的强大能力。架构、实现、测试和文档均由人类与 AI 协作完成。

主要增强功能

在原始基础概念上，此版本扩展了以下功能：

• 完整的架构重新设计：专业的模块化工具系统（v1.5.0+）
• 33 个 MCP 工具：从基础功能扩展到企业级项目管理
• 高级迭代管理：完整的里程碑跟踪和详细统计
• 增强的问题管理：涵盖完整问题生命周期，并支持关联迭代
• 批量操作：高效批量创建大型项目（v1.6.0）
• 高级查询系统：支持类似 SQL 的语法，可进行复杂数据筛选（v1.6.1）
• 团队协作：完整的评论系统，提升沟通效率（v1.7.0）
• 文件管理：完整的附件生命周期管理，并支持多种格式（v1.7.1）
• 史诗级需求管理：企业级大型项目组织管理（v1.8.0）
• 专业代码质量：错误处理、格式化和全面测试
• 完善的文档：提供 3 种语言的专业指南和示例
• 自动化 CI/CD：双注册表发布，全流程自动化

原始概念：基础 Taiga MCP 连接
此实现：采用全新架构的全功能 Taiga 项目管理套件

此重新实现肯定了基础概念，并展示了 AI 辅助软件开发的协作潜力。

📚 文档

完整文档请参阅我们的 GitHub Wiki 📖

🌐 多语言支持

我们的文档提供 3 种语言版本：

• 🇺🇸 English - 完整的英文文档
• 🇨🇳 简体中文 - 完整的简体中文文档
• 🇹🇼 繁體中文 - 完整的繁體中文文件

🎯 快速导航

章节	英文	简体中文	繁體中文
入门指南	安装指南	安装指南	安裝指南
API 参考	API 参考	API 参考	API 參考
架构	架构	架构概览	架構概覽
CI/CD 指南	CI/CD 指南	CI/CD 指南	CI/CD 指南

👩‍💻 开发者资源

主题	English	简体中文	繁體中文
设计文档	Design	设计文档	設計文件
入门	First Steps	第一步	第一步
配置	Configuration	配置说明	設定說明

💡 提示：Wiki 提供更便捷的搜索、导航和移动端体验！

🚀 自动化发布

本项目采用全自动 CI/CD 流水线：

npm version patch              # Create new version
git push origin main --tags    # Trigger automated publishing

自动化流程：测试 → NPM 发布 → GitHub Packages → 创建 Release
双仓库支持：可通过 NPM 和 GitHub Package Registry 获取
完整文档：请参阅 CI/CD 指南，了解完整设置方法

🤝 参与贡献

欢迎提交问题和拉取请求！请访问我们的 GitHub 仓库参与贡献。

📄 许可证

ISC License - 本项目采用 ISC License，与原始项目 mcpTAIGA 相同。

项目信息

• 灵感来源：adriapedralbes / mcpTAIGA
• 本项目实现：由 [email protected] 在 Claude Code 的 AI 辅助下进行了大幅重写
• 许可证：ISC License
• 架构：全新模块化设计，包含 11 个类别中的 33 个 MCP 工具
• 当前版本：v1.8.0 - 企业集成版，包含 Epic 管理

---

为使用 Taiga 项目管理的敏捷团队倾情打造 ❤️