CircleCI

先決條件：

• CircleCI Personal API token（了解更多）
• NPX：Node.js >= v18 與 pnpm
• Docker：Docker

在本地 MCP 伺服器中使用 NPX

將以下內容新增到您的 Cursor MCP 設定：

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

CIRCLECI_BASE_URL 為選用 — 僅供內部部署（on-prem）客戶使用。 MAX_MCP_OUTPUT_LENGTH 為選用 — MCP 回應的最大輸出長度（預設值：50000）。

在本地 MCP 伺服器中使用 Docker

將以下內容新增到您的 Cursor MCP 設定：

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

使用自管理遠端 MCP 伺服器

請參閱 自管理遠端 MCP 伺服器。使用每位使用者用戶端設定，並將其新增到您的 Cursor MCP 設定（Cursor Settings → MCP）。

先決條件：

• CircleCI Personal API token（了解更多）
• NPX：Node.js >= v18 與 pnpm
• Docker：Docker

在本地 MCP 伺服器中使用 NPX

將以下內容新增到您專案中的 .vscode/mcp.json：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

💡 首次啟動伺服器時會提示輸入，之後由 VS Code 安全儲存。

在本地 MCP 伺服器中使用 Docker

將以下內容新增到您專案中的 .vscode/mcp.json：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

使用自管理遠端 MCP 伺服器

請參閱 自管理遠端 MCP 伺服器。在 .vscode/mcp.json 中使用每位使用者用戶端設定。

先決條件：

• CircleCI Personal API token（了解更多）
• NPX：Node.js >= v18 與 pnpm
• Docker：Docker

在本地 MCP 伺服器中使用 NPX

將以下內容新增到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

在本地 MCP 伺服器中使用 Docker

將以下內容新增到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

使用自管理遠端 MCP 伺服器

請參閱 自管理遠端 MCP 伺服器。依照 Claude Desktop 與 CLI 用戶端 中的說明建立包裝腳本，然後將您的 claude_desktop_config.json 指向該腳本。

若要尋找或建立您的設定檔，請開啟 Claude Desktop 設定，按一下左側邊欄中的 Developer，然後按一下 Edit Config。設定檔位於：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

更多資訊：https://modelcontextprotocol.io/quickstart/user

先決條件：

• CircleCI Personal API token（了解更多）
• NPX：Node.js >= v18 與 pnpm
• Docker：Docker

在本地 MCP 伺服器中使用 NPX

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest

在本地 MCP 伺服器中使用 Docker

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com -- docker run --rm -i -e CIRCLECI_TOKEN -e CIRCLECI_BASE_URL circleci/mcp-server-circleci

使用自管理遠端 MCP 伺服器

請參閱 自管理遠端 MCP 伺服器 以及其中的 Claude Code 用戶端設定。

先決條件：

• CircleCI Personal API token（了解更多）
• NPX：Node.js >= v18 與 pnpm
• Docker：Docker

在本地 MCP 伺服器中使用 NPX

將以下內容新增到您的 Windsurf mcp_config.json：

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

在本地 MCP 伺服器中使用 Docker

將以下內容新增到您的 Windsurf mcp_config.json：

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

使用自管理遠端 MCP 伺服器

請參閱 自管理遠端 MCP 伺服器。在您的 Windsurf mcp_config.json 中使用每位使用者用戶端設定。

更多資訊：https://docs.windsurf.com/windsurf/mcp

先決條件：

• CircleCI Personal API token（了解更多）
• NPX：Node.js >= v18 與 pnpm

Amazon Q Developer 中的 MCP 用戶端設定以 JSON 格式儲存在名為 mcp.json 的檔案中。支援兩個層級的設定：

• 全域： ~/.aws/amazonq/mcp.json — 適用於所有工作區
• 工作區： .amazonq/mcp.json — 僅適用於目前的工作區

如果兩個檔案都存在，其內容會合併。若發生衝突，工作區設定優先。

在本地 MCP 伺服器中使用 NPX

編輯 ~/.aws/amazonq/mcp.json 或建立 .amazonq/mcp.json，內容如下：

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      },
      "timeout": 60000
    }
  }
}

使用自管理遠端 MCP 伺服器

請參閱 自管理遠端 MCP 伺服器。使用如 Claude Desktop 與 CLI 用戶端 所示的包裝腳本，然後使用 q mcp add 註冊。

先決條件：

• CircleCI Personal API token（了解更多）
• NPX：Node.js >= v18 與 pnpm

在本地 MCP 伺服器中使用 NPX

編輯 ~/.aws/amazonq/mcp.json 或建立 .amazonq/mcp.json，內容如下：

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      },
      "timeout": 60000
    }
  }
}

使用自管理遠端 MCP 伺服器

請參閱 自管理遠端 MCP 伺服器。使用如 Claude Desktop 與 CLI 用戶端 所示的包裝腳本，然後透過 MCP 設定 UI 新增：

1. 存取 MCP 設定 UI
2. 選擇 + 符號
3. 選擇範圍：global 或 local
4. 輸入名稱（例如 circleci-remote-mcp）
5. 選擇傳輸協定：stdio
6. 輸入您腳本的指令路徑
7. 按一下 Save

若要透過 Smithery 自動為 Claude Desktop 安裝 CircleCI MCP 伺服器：

npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude

範例：「找出我分支上最新失敗的 pipeline 並取得日誌」 — 更多範例請參閱 wiki。

https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74

透過提供指引和驗證來協助 CircleCI 設定任務。

• 驗證您的 .circleci/config.yml 的語法和語意錯誤
• 提供詳細的驗證結果和設定建議
• 範例：「驗證我的 CircleCI 設定」

從 CircleCI Usage API 下載指定組織的使用量資料。接受彈性的日期輸入（例如「2025 年 3 月」或「上個月」）。僅限雲端功能。

選項 1： 啟動新的匯出任務，提供：

• orgId、startDate、endDate（最多 32 天）、outputDir

選項 2： 檢查/下載現有的匯出任務，提供：

• orgId、jobId、outputDir

傳回包含指定時間範圍內 CircleCI 使用量資料的 CSV 檔案。

[!NOTE] 使用量資料可以輸入 find_underused_resource_classes 工具進行成本最佳化分析。

透過分析測試執行歷史記錄來識別 CircleCI 專案中的不穩定測試（flaky tests）。利用 CircleCI 的不穩定測試偵測功能。

此工具可用三種方式：

1. 使用專案 Slug（建議）：

   • 先使用 list_followed_projects 取得您的專案，然後：
   • 範例：「取得 my-project 的不穩定測試」

2. 使用 CircleCI 專案 URL：

   • 範例：「在 https://app.circleci.com/pipelines/github/org/repo 中尋找不穩定測試」

3. 使用本機專案內容：

   • 從您的本機工作區運作，提供工作區根目錄和 git 遠端 URL
   • 範例：「在我目前的專案中尋找不穩定測試」

輸出模式：

• 文字（預設）： 以文字格式傳回不穩定測試詳細資訊
• 檔案（需要 FILE_OUTPUT_DIRECTORY 環境變數）：建立包含不穩定測試詳細資訊的目錄

分析 CircleCI 使用量資料 CSV 檔案，找出平均或最大 CPU/RAM 使用量低於指定閾值（預設：40%）的任務。

提供從 download_usage_api_data 取得的 CSV 檔案。

傳回按專案和工作流程組織的未充分利用任務 Markdown 清單 — 有助於識別成本最佳化機會。

從 CircleCI 建置中擷取詳細的失敗日誌。此工具可用三種方式：

1. 使用專案 Slug 和分支（建議）：

   • 先使用 list_followed_projects 取得您的專案，然後：
   • 範例：「取得 my-project 在 main 分支上的建置失敗」

2. 使用 CircleCI URL：

   • 直接提供失敗的任務 URL 或 pipeline URL
   • 範例：「從 https://app.circleci.com/pipelines/github/org/repo/123 取得日誌」

3. 使用本機專案內容：

   • 從您的本機工作區運作，提供工作區根目錄、git 遠端 URL 和分支名稱
   • 範例：「找出我目前分支上最新失敗的 pipeline」

此工具傳回格式化日誌，包括：

• 任務名稱
• 逐步執行詳細資訊
• 失敗訊息和內容

擷取 CircleCI 任務的測試中繼資料，讓您無需離開 IDE 即可分析測試結果。此工具可用三種方式：

1. 使用專案 Slug 和分支（建議）：

   • 範例：「取得 my-project 在 main 分支上的測試結果」

2. 使用 CircleCI URL：

   • 任務 URL：https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789
   • 工作流程 URL：https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def
   • Pipeline URL：https://app.circleci.com/pipelines/github/org/repo/123

3. 使用本機專案內容：

   • 從您的本機工作區運作，提供工作區根目錄、git 遠端 URL 和分支名稱

此工具傳回：

• 所有測試的摘要（總數、成功、失敗）
• 失敗測試的詳細資訊：名稱、類別、檔案、錯誤訊息、持續時間
• 成功測試清單（含時間）
• 依測試結果篩選

[!NOTE] 測試中繼資料必須在您的 CircleCI 設定中設定。設定說明請參閱收集測試資料。

1. 使用專案 Slug 與分支（建議）：

   • 範例：「取得 my-project 在 main 分支上最新管線的狀態」

2. 使用 CircleCI 專案 URL：

   • 範例：「取得 https://app.circleci.com/pipelines/github/org/repo 最新管線的狀態」

3. 使用本機專案內容：

   • 從您的本機工作區運作，提供工作區根目錄、git 遠端 URL 與分支名稱

範例輸出：

---
Workflow: build
Status: success
Duration: 5 minutes
Created: 4/20/2025, 10:15:30 AM
Stopped: 4/20/2025, 10:20:45 AM
---
Workflow: test
Status: running
Duration: unknown
Created: 4/20/2025, 10:21:00 AM
Stopped: in progress

擷取 CircleCI 工作產生的成品清單。此工具可用三種方式使用：

1. 使用專案 Slug 與分支（建議）：

   • 先使用 list_followed_projects 取得您的專案，然後：
   • 範例：「列出 my-project 在 main 分支上的成品」

2. 使用 CircleCI URL：

   • 工作 URL：https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
   • 工作流程 URL：https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
   • 管線 URL：https://app.circleci.com/pipelines/gh/organization/project/123

3. 使用本機專案內容：

   • 從您的本機工作區運作，提供工作區根目錄、git 遠端 URL 與分支名稱

適用於：

• 尋找建置成品（二進位檔、報告、日誌）的下載 URL
• 檢查管線執行產生了哪些成品

列出環境中特定 CircleCI 元件的所有版本。包含部署狀態、提交資訊與時間戳記。

若未提供元件與環境，工具會提示您進行選擇。

適用於：

• 識別目前上線的版本
• 選擇用於回滾操作的目標版本
• 取得部署詳細資訊（管線、工作流程、工作）

列出使用者在 CircleCI 上追蹤的所有專案。

• 顯示您有權存取的所有專案及其 projectSlug
• 範例：「列出我的 CircleCI 專案」

範例輸出：

Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)

[!NOTE] 許多其他 CircleCI 工具需要 projectSlug（而非專案名稱）。

從起點或失敗的工作重新執行工作流程。

傳回新建立工作流程的 ID 以及用於監控的連結。

觸發管線執行。此工具可用三種方式使用：

1. 使用專案 Slug 與分支（建議）：

   • 範例：「為 my-project 在 main 分支上執行管線」

2. 使用 CircleCI URL：

   • 管線 URL、工作流程 URL、工作 URL 或含分支的專案 URL
   • 範例：「為 https://app.circleci.com/pipelines/github/org/repo/123 執行管線」

3. 使用本機專案內容：

   • 從您的本機工作區運作，提供工作區根目錄、git 遠端 URL 與分支名稱

工具會傳回用於監控管線執行的連結。

觸發 CircleCI 專案的回滾。工具會以互動方式引導您完成：

1. 專案選擇 — 列出您追蹤的專案供您選擇
2. 環境選擇 — 列出可用的環境（若只有一個則自動選取）
3. 元件選擇 — 列出可用的元件（若只有一個則自動選取）
4. 版本選擇 — 顯示可用的版本；您選擇回滾的目標
5. 回滾模式偵測 — 檢查是否已設定回滾管線
6. 執行回滾 — 兩個選項：
   • 管線回滾： 觸發回滾管線
   • 工作流程重新執行： 使用工作流程 ID 重新執行先前的工作流程
7. 確認 — 在執行前進行摘要與確認

最常見的問題：

1. 清除套件快取：

   npx clear-npx-cache
   npm cache clean --force
   

2. 強制使用最新版本： 在您的設定中加入 @latest：

   "args": ["-y", "@circleci/mcp-server-circleci@latest"]
   

3. 完全重新啟動您的 IDE（不只是重新載入視窗）

• 無效的權杖錯誤： 在 Personal API Tokens 中驗證您的 CIRCLECI_TOKEN
• 權限錯誤： 確保權杖對您的專案具有讀取權限
• 環境變數未載入： 使用 echo $CIRCLECI_TOKEN（Mac/Linux）或 echo %CIRCLECI_TOKEN%（Windows）進行測試

• Base URL： 確認 CIRCLECI_BASE_URL 為 https://circleci.com
• 公司網路： 若位於防火牆後方，請設定 npm 代理伺服器設定
• 防火牆封鎖： 檢查安全軟體是否封鎖套件下載

• Node.js 版本： 確保 >= 18.0.0 且具備 node --version
• 更新 Node.js： 若遇到相容性問題，請考慮使用最新的 LTS 版本
• 套件管理員： 驗證 npm/pnpm 是否正常運作：npm --version

• 設定檔位置： 再次確認您作業系統的路徑
• 語法錯誤： 驗證設定檔中的 JSON 語法
• 主控台日誌： 檢查 IDE 開發者主控台以取得特定錯誤
• 嘗試不同的 IDE： 在其他支援的編輯器中測試以隔離問題

卡住的程序 — 終止現有的 MCP 程序：

# Mac/Linux:
pkill -f "mcp-server-circleci"

# Windows:
taskkill /f /im node.exe

連接埠衝突： 若連線似乎被封鎖，請重新啟動您的 IDE。

• 直接測試套件： npx @circleci/mcp-server-circleci@latest --help
• 詳細日誌： DEBUG=* npx @circleci/mcp-server-circleci@latest
• Docker 備援方案： 若 npx 持續失敗，請嘗試 Docker 安裝

仍需要協助？

1. 在 GitHub Issues 中查看類似的問題
2. 回報問題時請附上您的作業系統、Node 版本與 IDE
3. 分享 IDE 主控台中的相關錯誤訊息