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 为可选项——仅本地部署客户需要。 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 设置，点击左侧边栏中的 开发者，然后点击 编辑配置。配置文件位于：

• 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. 选择范围：全局 或 本地
4. 输入名称（例如 circleci-remote-mcp）
5. 选择传输协议：stdio
6. 输入脚本的命令路径
7. 点击 保存

通过 Smithery 为 Claude Desktop 自动安装 CircleCI MCP 服务器：

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

示例："找到我分支上最近失败的管道并获取日志" ——更多示例请参阅维基。

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

通过提供指导和验证来协助 CircleCI 配置任务。

• 验证你的 .circleci/config.yml 是否存在语法和语义错误
• 提供详细的验证结果和配置建议
• 示例："验证我的 CircleCI 配置"

从 CircleCI Usage API 下载指定组织的使用数据。接受灵活日期输入（例如 "March 2025" 或 "last month"）。仅限云版本功能。

选项 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 主分支上的构建失败信息"

2. 使用 CircleCI URL：

   • 直接提供失败的任务 URL 或管道 URL
   • 示例："从 https://app.circleci.com/pipelines/github/org/repo/123 获取日志"

3. 使用本地项目上下文：

   • 通过提供工作区根目录、git 远程 URL 和分支名称从本地工作区工作
   • 示例："查找我当前分支上最近失败的管道"

该工具返回格式化的日志，包括：

• 任务名称
• 逐步执行详情
• 失败消息和上下文

检索 CircleCI 任务的测试元数据，让你无需离开 IDE 即可分析测试结果。此工具可以通过三种方式使用：

1. 使用项目 Slug 和分支（推荐）：

   • 示例："获取 my-project 主分支上的测试结果"

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. 使用项目标识和分支（推荐）：

   • 示例："获取 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. 使用项目标识和分支（推荐）：

   • 首先使用 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. 使用项目标识和分支（推荐）：

   • 示例："为 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（不仅仅是重新加载窗口）

• 无效令牌错误： 在个人 API 令牌中验证您的 CIRCLECI_TOKEN
• 权限错误： 确保令牌对您的项目具有读取权限
• 环境变量未加载： 使用 echo $CIRCLECI_TOKEN（Mac/Linux）或 echo %CIRCLECI_TOKEN%（Windows）进行测试

• 基础 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 控制台中的相关错误消息