CircleCI MCP伺服器專案介紹

專案概述

CircleCI MCP伺服器是專為模型上下文協定(MCP)設計的專業伺服器實現，旨在整合CircleCI的開發工作流程。該專案作為CircleCI基礎設施與模型上下文協定之間的橋樑，提供增強的AI驅動開發體驗。

該伺服器讓AI工具如Cursor、Claude Code、Windsurf等能夠理解您的建構系統。它基於模型上下文協定(MCP)構建，這是一個輕量級標準，允許LLM驅動的代理從外部系統獲取結構化資料。

核心功能

主要工具和功能

1. get_build_failure_logs

檢索CircleCI建構的詳細失敗日誌。該工具支援兩種使用方式：

使用CircleCI URL:

直接提供失敗作業URL或流水線URL
示例: "獲取 https://app.circleci.com/pipelines/github/org/repo/123 的日誌"

使用本地專案上下文:

透過提供以下資訊從本地工作空間工作：
- 工作空間根路徑
- Git遠端URL
- 分支名稱
示例: "查找我目前分支上最新的失敗流水線"

返回的格式化日誌包括：

作業名稱
分步執行詳情
失敗訊息和上下文

2. find_flaky_tests

透過分析測試執行歷史識別CircleCI專案中的不穩定測試。支援兩種使用方式：

使用CircleCI專案URL:

直接從CircleCI提供專案URL
示例: "在 https://app.circleci.com/pipelines/github/org/repo 中查找不穩定測試"

使用本地專案上下文:

透過提供工作空間根路徑和Git遠端URL從本地工作空間工作

返回不穩定測試的詳細資訊，包括：

測試名稱和檔案位置
失敗訊息和上下文

3. get_latest_pipeline_status

檢索給定分支最新流水線的狀態。工具返回最新流水線的格式化狀態：

工作流程名稱及其目前狀態
每個工作流程的持續時間
建立和完成時間戳記
整體流水線健康狀況

示例輸出：

--- 
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

4. get_job_test_results

檢索CircleCI作業的測試元資料，允許您在不離開IDE的情況下分析測試結果。

返回詳細的測試結果資訊：

所有測試的摘要（總數、成功、失敗）
失敗測試的詳細資訊，包括：
- 測試名稱和類別
- 檔案位置
- 錯誤訊息
- 執行時持續時間
帶有時間資訊的成功測試列表

5. config_helper

協助CircleCI配置任務，提供指導和驗證。該工具幫助您：

驗證CircleCI配置：
- 檢查您的 .circleci/config.yml 是否存在語法和語義錯誤
- 示例: "驗證我的CircleCI配置"

提供：

詳細的驗證結果
配置建議

6. create_prompt_template

基於功能需求生成結構化提示範本，用於AI啟用的應用程式。該工具：

將功能需求轉換為結構化提示：
- 將使用者需求轉換為優化的提示範本
- 示例: "為按年齡和主題生成睡前故事建立提示範本"

7. recommend_prompt_template_tests

為提示範本生成測試用例，確保它們產生預期結果。

安裝和配置

系統要求

pnpm套件管理器 - 了解更多
Node.js >= v18.0.0
CircleCI API令牌 - 您可以透過CircleCI生成一個。了解更多或點擊這裡快速訪問

支援的IDE和工具

Cursor IDE

將以下內容添加到您的cursor MCP配置：

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // 可選 - 僅本地部署客戶需要
      }
    }
  }
}

VS Code

在 .vscode/mcp.json 中安裝CircleCI MCP伺服器：

{
  // 💡 輸入在首次伺服器啟動時提示，然後由VS Code安全儲存
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}"
      }
    }
  }
}

Claude Desktop

將以下內容添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // 可選 - 僅本地部署客戶需要
      }
    }
  }
}

配置文件位置：

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

Claude Code

安裝Claude Code後，執行以下命令：

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

Windsurf

將以下內容添加到您的windsurf mcp_config.json：

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // 可選 - 僅本地部署客戶需要
      }
    }
  }
}

自動安裝

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

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

開發和貢獻

本地開發設定

克隆倉庫：

git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci

安裝依賴：

pnpm install

建構專案：

pnpm build

使用MCP檢查器進行開發

最簡單的MCP伺服器迭代方式是使用MCP檢查器。

啟動開發伺服器：

pnpm watch # 在一個終端中保持運行

在單獨的終端中啟動檢查器：

pnpm inspector

配置環境：
- 在檢查器UI的環境變數部分新增您的 CIRCLECI_TOKEN
- 令牌需要對您的CircleCI專案的讀取權限
- 可選擇設定您的CircleCI基礎URL，預設為 https://circleci.com

測試

運行測試套件：

pnpm test

在開發期間以監視模式運行測試：

pnpm test:watch

應用場景

該工具特別適用於：

偵錯失敗的建構
分析測試失敗
調查部署問題
在不離開IDE的情況下快速訪問建構日誌
檢查最新流水線的狀態
識別測試套件中不可靠的測試
對測試改進做出資料驅動的決策

專案優勢

CircleCI MCP伺服器專為支援開發生命週期中的實際時刻而設計。無論您是在審查失敗的建構、偵錯失敗的部署，還是關注關鍵分支，它都能幫助您的助手在幾秒鐘內理解失敗並建議修復方案——無需上下文切換。

透過整合這個MCP伺服器，開發者可以：

使用自然語言與CircleCI互動
在熟悉的開發環境中獲取建構資訊
快速診斷和解決CI/CD問題
提高開發工作流程的效率

mcp-server-circleci