PingCode MCP Server

这是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在让 AI 助手（如 Claude Desktop, Cursor 等）能够直接与 PingCode 项目管理平台进行交互。

通过此 MCP Server，您的 AI 助手可以查询 PingCode 中的项目、工作项（任务、缺陷、需求等）、成员信息等。

功能特性

目前支持以下工具（Tools）：

鉴权 (Auth)

• pingcode_get_enterprise_token: 获取企业令牌（client_id/client_secret 来自环境变量）。

目录服务 (Directory)

• pingcode_get_current_team: 获取当前 PingCode 团队信息。
• pingcode_get_team_members: 获取企业成员列表，支持通过姓名、用户名模糊搜索，或通过部门 ID 筛选。

项目与工作项 (Project & Work Items)

• pingcode_get_workitem_types: 获取指定项目的工作项类型列表（如：用户故事、缺陷、任务等）。
• pingcode_get_workitem_states: 获取指定项目和工作项类型下的状态列表（如：新建、进行中、已完成）。
• pingcode_get_workitems: 强大的工作项查询工具。支持多种筛选条件：
  • 关键字搜索（标题、编号）
  • 项目 ID、工作项类型 ID
  • 负责人、创建人
  • 状态、优先级
  • 时间范围（创建时间、更新时间、开始/结束时间）
  • 迭代、看板、版本等
• pingcode_create_workitem: 创建新的工作项。支持设置：
  • 必需参数：项目 ID、标题、工作项类型 ID
  • 可选参数：描述、负责人、优先级、状态、父工作项、迭代、开始/结束日期、标签等
• pingcode_update_workitem: 更新单个工作项。支持更新：
  • 标题、描述、负责人、优先级、状态、父工作项、迭代、开始/结束日期、标签等
• pingcode_batch_update_workitems: 批量更新多个工作项。支持批量修改状态、负责人、优先级等。
• pingcode_batch_create_workitems: 批量创建多个工作项。适用于需要一次性创建大量工作项的场景。
• pingcode_delete_workitem: 删除指定的工作项。
• pingcode_get_workitem_attributes: 获取工作项属性列表。
• pingcode_get_workitem_priorities: 获取工作项优先级列表（如：高、中、低、紧急）。
• pingcode_get_workitem_tags: 获取项目中所有工作项标签列表。
• pingcode_add_workitem_tag: 为指定工作项添加标签。
• pingcode_remove_workitem_tag: 从指定工作项移除标签。
• pingcode_get_workitem_association_types: 获取工作项关联类型列表（如：阻塞、依赖、相关、子任务等）。
• pingcode_get_workitem_associations: 获取指定工作项的所有关联关系。
• pingcode_create_workitem_association: 建立两个工作项之间的关联关系。
• pingcode_delete_workitem_association: 删除两个工作项之间的关联关系。

安装与配置

前置要求

• Node.js (推荐 v18 或更高版本)
• PingCode 账号及 API 访问权限

1. 获取代码

git clone https://gitlab.shencom.cn/web/tools/pingcode-mcp.git
cd pingcode-mcp

2. 安装依赖并构建

npm install
npm run build

3. 获取 PingCode API 配置

你需要从 PingCode 获取以下信息：

• API Endpoint (PINGCODE_OPEN_API_ENDPOINT): 通常为 https://open.pingcode.com/v1 或者你的私有部署地址。
• Access Token (PINGCODE_OPEN_API_ACCESS_TOKEN): 在 PingCode 后台或个人设置中生成的 Access Token。
• Client ID (PINGCODE_OPEN_API_CLIENT_ID): 应用的客户端 ID（获取企业令牌时使用）。
• Client Secret (PINGCODE_OPEN_API_CLIENT_SECRET): 应用的客户端密钥（获取企业令牌时使用）。

使用指南

工作项创建示例

使用 pingcode_create_workitem 工具创建新的工作项：

{
  "tool": "pingcode_create_workitem",
  "arguments": {
    "project_id": "your-project-id",
    "title": "新功能开发",
    "type_id": "user-story-id",
    "description": "实现用户登录功能",
    "assignee_id": "user-id",
    "priority_id": "high-priority-id",
    "sprint_id": "current-sprint-id"
  }
}

在 Claude Desktop 中使用

编辑 Claude Desktop 的配置文件（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json on macOS 或 %APPDATA%\Claude\claude_desktop_config.json on Windows）：

{
  "mcpServers": {
    "pingcode": {
      "command": "node",
      "args": [
        "/path/to/pingcode-mcp/dist/index.js"
      ],
      "env": {
        "PINGCODE_OPEN_API_ACCESS_TOKEN": "your-access-token-here",
        "PINGCODE_OPEN_API_CLIENT_ID": "your-client-id-here",
        "PINGCODE_OPEN_API_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

请将 /path/to/pingcode-mcp 替换为实际的项目路径，将 your-access-token-here 替换为真实的 Token。

在 Cursor 中使用

1. 打开 Cursor 设置面板。
2. 进入 Features -> MCP Servers。
3. 点击 + Add New MCP Server。
4. 填写如下信息：

完整配置示例：

• Name: pingcode (或任意名称)
• Type: command
• Command: node
• Args: /path/to/pingcode-mcp/dist/index.js (请使用绝对路径，替换为你的实际路径)
• Environment Variables: 添加以下变量
  • PINGCODE_OPEN_API_ACCESS_TOKEN: your-access-token-here (替换为你的真实 Token)
  • PINGCODE_OPEN_API_CLIENT_ID: your-client-id-here
  • PINGCODE_OPEN_API_CLIENT_SECRET: your-client-secret-here

注意事项：

• Command 应该填写 node，而不是直接填写完整路径
• 脚本文件的路径应该填写在 Args 字段中，使用绝对路径

在 Claude Code 中使用（推荐）

本项目包含 Claude Code 插件，提供更便捷的交互体验。

安装

1. 设置环境变量：

   export PINGCODE_OPEN_API_ACCESS_TOKEN="your-pingcode-api-token"

   添加到 ~/.zshrc 或 ~/.bashrc 使其永久生效。

2. 安装插件：

   cc --plugin-dir /path/to/pingcode-mcp-server/plugin

3. 重新加载 Claude Code

可用命令

| 命令 | 说明 | |------|------| | /pingcode-query [编号] | 查询工作项详情 | | /pingcode-prd [编号] | 生成 PRD 文档 | | /pingcode-create-workitem [项目ID] [标题] [类型] | 创建新工作项 |

创建工作项示例

/pingcode-create-workitem

Claude 会引导你输入：

1. 项目 ID - 目标项目
2. 标题 - 工作项标题
3. 类型 - 选择工作项类型（任务、缺陷、用户故事等）
4. 可选信息 - 描述、负责人、优先级、迭代等

也可以直接提供参数：

/pingcode-create-workitem 项目XSG 实现用户登录功能 任务

自动触发场景

当用户提及以下内容时，插件会自动激活：

• 工作项编号（如 XSG-123、#XSG-123）
• 请求"分析"或"生成 PRD"
• 查询项目成员、状态、迭代
• 按负责人或状态过滤工作项
• 在 feature/epic 下创建子工作项

开发调试

启动 Inspector

MCP 提供了一个 Inspector 工具用于调试服务器：

npm run inspector

监听模式

如果你在开发过程中需要实时编译：

npm run watch

许可证

ISC