CircleCI MCP Server

必要條件：

• CircleCI 個人 API 權杖（了解更多）
• 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 為選用 — 僅限內部部署客戶需要。 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 >= 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 個人 API 權杖（了解更多）
• 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 個人 API 權杖（了解更多）
• 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 個人 API 權杖（了解更多）
• 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 個人 API 權杖（了解更多）
• 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 個人 API 權杖（了解更多）
• 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. 選擇範圍：全域 或 本機
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

分析 git 差異對照游標規則，以識別規則違規。

提供：

• Git 差異內容（例如 git diff --cached、git diff HEAD）
• 來自 .cursorrules 或 .cursor/rules 的儲存庫規則

傳回詳細的違規報告，包含信心分數和說明。

適用於：

• 提交前程式碼品質檢查
• 確保符合團隊編碼標準
• 在程式碼審查前捕捉規則違規

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

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

根據功能需求，為 AI 驅動的應用程式產生結構化提示範本。

• 將使用者需求轉換為最佳化的提示範本
• 傳回結構化範本和定義必要輸入參數的內容結構描述
• 範例：「建立一個按年齡和主題產生睡前故事的提示範本」

從 CircleCI 使用量 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 遠端 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 和用於監控的連結。

在 CircleCI 管線上執行評估測試（也稱為「提示測試」）。產生適當的 CircleCI 設定並使用它觸發管線。

此工具可以三種方式使用：

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

   • 首先使用 list_followed_projects 取得您的專案，然後：
   • 範例：「為 my-project 在 main 分支上執行評估測試」

2. 使用 CircleCI URL：

   • 專案 URL、管線 URL、工作流程 URL 或作業 URL
   • 範例：「為 https://app.circleci.com/pipelines/gh/organization/project/123 執行評估測試」

3. 使用本機專案內容：

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

此工具接受提示範本檔案，並傳回用於監控已觸發管線的 URL。

[!NOTE] 如果專案有多個管線定義，此工具將傳回可用管線清單供您選擇。

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

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

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

2. 使用 CircleCI URL：

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

3. 使用本機專案內容：

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

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

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（不僅僅是重新載入視窗）

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

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

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