PingCode MCP

讓 VS Code、Cursor、Qoder、ZCode 等 Coding Agent 安全連接 PingCode：讀取 Wiki、工作項目、Test Case 與測試庫上下文，並以 Preview → Approval → Commit 流程控管寫入與同步。適合 UAT 規劃、需求追蹤和測試資料維護，不提供任意 REST API 代理。

支援範圍

支援 Wiki、Task／工作項目、Test Case、測試庫、Project、Ship、Relation、使用者與成員角色的讀取，以及受控的 Task／Test Case、Project、Test Library、Ship、Relation、成員角色與需求模組寫入流程。寫入固定要求獨立權限、Preview、有效 Approval、幂等與稽核。

不支援 Wiki 寫入、Task／Project／Test Library／Idea 刪除或任意 PingCode REST API 代理；也不會主動刪除關係另一端資源。

Related MCP server: gitbook-mcp

快速安裝（推薦）

需要 Node.js 20 以上，以及在 PingCode 建立的 enterprise 應用程式憑據。npm 套件是 scoped package @xurenxiang1219/pingcode-mcp；請保留 scope，避免安裝到另一個同名套件。

1. 設定 PingCode 憑據

有兩種方式，選一種即可。

推薦：使用私有環境檔

將 .env.stdio.local.example 複製到只供本機使用的位置（例如 /absolute/private/path/pingcode-mcp.env），填入：

PINGCODE_AUTH_MODE=enterprise
PINGCODE_CLIENT_ID=your-pingcode-client-id
PINGCODE_CLIENT_SECRET=your-pingcode-client-secret

懶人模式：直接放進 Client 的 env

不想另外建立環境檔時，可以直接在 MCP 設定的 env 中加入：

"env": {
  "PINGCODE_AUTH_MODE": "enterprise",
  "PINGCODE_CLIENT_ID": "your-pingcode-client-id",
  "PINGCODE_CLIENT_SECRET": "your-pingcode-client-secret"
}

這種方式最省事，但 Secret 會以明文保存在 Client 設定檔，只建議用於個人本機；不要提交、同步或分享該設定。stdio 模式會在程序記憶體中產生短效 Approval Secret，不需要手動產生或貼上 Approval Token。

2. 連接 MCP Client

VS Code

在終端機執行以下命令，將 Server 加入 VS Code 的 MCP 設定。請把環境檔路徑換成你的絕對路徑：

code --add-mcp '{"name":"pingcode","command":"npx","args":["-y","@xurenxiang1219/pingcode-mcp","--stdio","--env-file","/absolute/private/path/pingcode-mcp.env"]}'

不想建立環境檔時，也可以直接在命令中傳入憑據：

code --add-mcp '{"name":"pingcode","command":"npx","args":["-y","@xurenxiang1219/pingcode-mcp","--stdio"],"env":{"PINGCODE_AUTH_MODE":"enterprise","PINGCODE_CLIENT_ID":"your-pingcode-client-id","PINGCODE_CLIENT_SECRET":"your-pingcode-client-secret"}}'

直接傳入的 Secret 會保存在 VS Code MCP 設定中，只建議用於個人本機；不要提交、同步或分享該設定。

也可以在工作區 .vscode/mcp.json 使用相同的 stdio Server；本 repository 已提供可直接使用的範例。

Cursor、Qoder、ZCode

這些 Client 使用 mcpServers 設定。將下列區塊放入各自的 MCP 設定檔（或在設定介面新增同等欄位），並替換環境檔的絕對路徑：

{
  "mcpServers": {
    "pingcode": {
      "command": "npx",
      "args": [
        "-y",
        "@xurenxiang1219/pingcode-mcp",
        "--stdio",
        "--env-file",
        "/absolute/private/path/pingcode-mcp.env"
      ]
    }
  }
}

不想建立環境檔時，使用下面的完整設定，直接填入 Client ID 與 Client Secret：

{
  "mcpServers": {
    "pingcode": {
      "command": "npx",
      "args": ["-y", "@xurenxiang1219/pingcode-mcp", "--stdio"],
      "env": {
        "PINGCODE_AUTH_MODE": "enterprise",
        "PINGCODE_CLIENT_ID": "your-pingcode-client-id",
        "PINGCODE_CLIENT_SECRET": "your-pingcode-client-secret"
      }
    }
  }
}

如 Client 不支援 --env-file 參數，也可改用 env 傳入 PINGCODE_ENV_FILE，讓 Server 從私有環境檔讀取：

{
  "mcpServers": {
    "pingcode": {
      "command": "npx",
      "args": ["-y", "@xurenxiang1219/pingcode-mcp", "--stdio"],
      "env": {
        "PINGCODE_ENV_FILE": "/absolute/private/path/pingcode-mcp.env"
      }
    }
  }
}

3. 啟動與首次寫入

啟動後先使用 Preview Tool 檢視變更，再由 Agent 呼叫對應的 Commit Tool。Server 會驗證 Preview hash、Approval Context、會話綁定、request hash、幂等鍵並記錄 auditId；是否顯示額外的 MCP Client 確認由 PINGCODE_WRITE_CONFIRMATION 控制（預設 required）。

stdio 本機模式不要求使用者手動生成 Approval Token；是否顯示額外確認由 PINGCODE_WRITE_CONFIRMATION 決定。

認證與環境變數

最小 stdio 設定只有以下三項：

程式也支援 --env-file /path/to/file、--env-file=/path/to/file，以及 PINGCODE_ENV_FILE。未指定時才會嘗試目前 package 目錄下的 .env。

進階：從原始碼執行

適合需要修改程式、執行測試或使用工作區 .vscode/mcp.json 的情境：

git clone https://github.com/xurenxiang1219/pingcode-mcp.git
cd pingcode-mcp
npm ci
cp .env.stdio.local.example .env
# 編輯 .env，填入 PINGCODE_CLIENT_ID 與 PINGCODE_CLIENT_SECRET
npm run build

完成後可在 VS Code 開啟此資料夾。.vscode/mcp.json 會以 ${workspaceFolder}/dist/index.js --stdio 啟動 Server，並讀取同資料夾的 .env。

也可以直接啟動 npm 套件：

npx -y @xurenxiang1219/pingcode-mcp --stdio --env-file /absolute/private/path/pingcode-mcp.env

首次發佈由 package 維護者執行 npm login 後再執行 npm publish --access public；本 repository 不會在開發或測試時自動發佈。

工具

唯讀與上下文

• pingcode_uat_runtime_info

• pingcode_wiki_list_spaces

• pingcode_wiki_list_pages

• pingcode_wiki_get_requirement_context

• pingcode_task_list

• pingcode_task_get

• pingcode_test_case_list

• pingcode_test_case_get

• pingcode_project_list

• pingcode_work_item_metadata_get

• pingcode_test_library_list

• pingcode_test_library_get

• pingcode_test_case_metadata_get

• pingcode_user_list

• pingcode_role_list

• pingcode_user_search

• pingcode_project_context_get

• pingcode_project_context_save

• pingcode_ship_product_list

• pingcode_ship_product_get

• pingcode_ship_idea_list

• pingcode_ship_product_idea_list

• pingcode_ship_idea_get

• pingcode_ship_product_suite_list

• pingcode_ship_product_suite_get

• pingcode_relation_list

• pingcode_relation_get

• pingcode_member_role_get

Preview、Commit 與受控寫入

• pingcode_test_case_delete_preview / pingcode_test_case_delete_commit

• pingcode_test_case_bulk_create_preview / pingcode_test_case_bulk_create_commit

• pingcode_ship_product_sync_preview / pingcode_ship_product_sync_commit

• pingcode_ship_idea_sync_preview / pingcode_ship_idea_sync_commit

• pingcode_task_sync_preview / pingcode_task_sync_commit

• pingcode_test_case_sync_preview / pingcode_test_case_sync_commit

• pingcode_ship_product_suite_create_preview / pingcode_ship_product_suite_create_commit

• pingcode_ship_product_suite_remove_preview / pingcode_ship_product_suite_remove_commit

• pingcode_relation_sync_preview / pingcode_relation_sync_commit

• pingcode_member_role_update_preview / pingcode_member_role_update_commit

• pingcode_project_create_preview / pingcode_project_create_commit

• pingcode_test_library_create_preview / pingcode_test_library_create_commit

安全機制與限制

• 唯讀與 Preview Tool 不修改 PingCode；所有 Commit Tool 都需要有效 Approval、不可變 request hash、Preview 證據、Approval Context、會話綁定和 idempotency key。

• PingCode 寫入請求不自動重試；結果不確定時，先用對應唯讀 Tool 回讀確認。

• Test Case 刪除必須先 Preview，再由獨立 Commit Tool 執行；完成後 MCP 會回讀確認用例不存在，並保留 Approval、hash、幂等鍵與稽核資料。

• 資源名稱、ID、成員與其他候選都必須來自 PingCode 目錄或使用者明確確認，不得猜測，也不得用空字串、@ 或 * 作為通配符。

• 需要建立 private 專案或重用既有上下文時，Agent 必須先取得使用者確認；沒有確認的唯一候選也不能直接套用。

• Client ID、Client Secret、Token、Cookie 與客戶資料只應放在本機私有環境或 Secret Manager，不要提交、同步或分享。

本機開發驗證

npm run typecheck
npm test
npm run build