PingCode MCP Server

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

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

功能特性

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

目录服务 (Directory)

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

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

• pingcode_get_workitem_types: 获取指定项目的工作项类型列表（如：用户故事、缺陷、任务等）。
• pingcode_get_workitem_states: 获取指定项目和工作项类型下的状态列表（如：新建、进行中、已完成）。
• pingcode_get_workitems: 强大的工作项查询工具。支持多种筛选条件：
  • 关键字搜索（标题、编号）
  • 项目 ID、工作项类型 ID
  • 负责人、创建人
  • 状态、优先级
  • 时间范围（创建时间、更新时间、开始/结束时间）
  • 迭代、看板、版本等

安装与配置

前置要求

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

1. 获取代码

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

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。

使用指南

在 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/mcp-pingcode/dist/index.js"
      ],
      "env": {
        "PINGCODE_OPEN_API_ENDPOINT": "https://open.pingcode.com/v1",
        "PINGCODE_OPEN_API_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}

请将 /path/to/mcp-pingcode 替换为实际的项目路径，将 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: /Users/xsl/web/github/mcp-pingcode/dist/index.js (请使用绝对路径，替换为你的实际路径)
• Environment Variables: 添加两个变量
  • PINGCODE_OPEN_API_ENDPOINT: https://open.pingcode.com/v1
  • PINGCODE_OPEN_API_ACCESS_TOKEN: your-access-token-here (替换为你的真实 Token)

注意事项：

• Command 应该填写 node，而不是直接填写完整路径
• 脚本文件的路径应该填写在 Args 字段中，使用绝对路径
• 如果你的项目路径不同，请将 /Users/xsl/web/github/mcp-pingcode 替换为你的实际项目路径

开发调试

启动 Inspector

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

npm run inspector

监听模式

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

npm run watch

许可证

ISC