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 是可选的——仅本地部署客户需要。 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 Server：

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 远程 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）进行测试

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