CircleCI MCP Server

前提条件：

• CircleCI Personal API token（了解更多）
• 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 Personal API token（了解更多）
• 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 Personal API token（了解更多）
• 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. 选择作用范围：全局或本地
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 获取的使用情况数据。支持灵活的日期输入（例如，“March 2025”或“last month”）。仅限 Cloud 使用。

选项 1： 提供以下信息以启动新的导出任务：

• orgId、startDate、endDate（最长 32 天）、outputDir

选项 2： 提供以下信息以检查或下载现有导出任务：

• orgId、jobId、outputDir

返回包含指定时间范围内 CircleCI 使用情况数据的 CSV 文件。

说明

使用情况数据可输入 find_underused_resource_classes 工具，用于成本优化分析。

通过分析测试执行历史，识别 CircleCI 项目中的不稳定测试。利用 CircleCI 的不稳定测试检测功能。

此工具可通过三种方式使用：

1. 使用项目标识（推荐）：

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

   • 首先使用 list_followed_projects 获取项目，然后：
   • 示例：“获取 my-project 在 main 分支上的构建失败信息”

2. 使用 CircleCI URL：

   • 直接提供失败作业 URL 或流水线 URL
   • 示例：“获取 https://app.circleci.com/pipelines/github/org/repo/123 中的日志”

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

   • 提供工作区根目录、git 远程 URL 和分支名称，即可在本地工作区中使用
   • 示例：“查找我当前分支上最新的失败流水线”

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

• 作业名称
• 分步执行详情
• 失败消息和上下文

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 和分支名称

此工具会返回：

• 所有测试的摘要（总数、成功数、失败数）
• 失败测试的详细信息：名称、类、文件、错误消息、耗时
• 成功测试列表及耗时
• 按测试结果筛选

说明

必须在 CircleCI 配置中配置测试元数据。有关设置说明，请参阅 Collect Test Data。

检索指定分支最新流水线的状态。此工具有三种使用方式：

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)

说明

许多其他 CircleCI 工具需要的是 projectSlug（而不是项目名称）。

从工作流起点或失败的作业处重新运行工作流。

返回新建工作流的 ID 和用于监控该工作流的链接。

触发流水线运行。此工具有三种使用方式：

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

   • 示例：“在 main 分支上运行 my-project 的流水线”

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 版本： 使用 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 控制台中的相关错误消息