CircleCI

先決條件：

• CircleCI 個人 API 權杖（深入了解）
• NPX：Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 與 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 個人 API 權杖（深入了解）
• NPX：Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 與 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 個人 API 權杖（深入了解）
• NPX：Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 與 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 個人 API 權杖（深入了解）
• NPX：Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 與 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 個人 API 權杖（深入了解）
• NPX：Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 與 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 個人 API 權杖（深入了解）
• NPX：Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 與 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 個人 API 權杖（深入了解）
• NPX：Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 與 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 設定介面加入它：

1. 存取 MCP 設定介面
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

範例：「尋找我的分支上最新失敗的管線並取得日誌」 — 更多範例請參閱 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 專案中的不穩定測試。運用 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 或管線 URL
   • 範例：「從 https://app.circleci.com/pipelines/github/org/repo/123 取得日誌」

3. 使用本機專案內容：

   • 提供工作區根目錄、git 遠端 URL 與分支名稱，即可從本機工作區運作
   • 範例：「尋找目前分支上最新失敗的管線」

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

• 工作名稱
• 逐步執行詳細資料
• 失敗訊息與內容

擷取 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
   • 管線 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 remote 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 remote 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 remote 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）測試

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

• Node.js 版本： 使用 node --version 確保其符合 ^22.23.4 || ^24.22.1 || >=26.12.1
• 更新 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 主控台中相關的錯誤訊息