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 配置界面添加它：

1. 访问 MCP 配置界面
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

示例：“查找我分支上最新的失败流水线并获取日志” — 更多示例请参阅 wiki。

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

根据游标规则分析 git diff，识别规则违规。

提供：

• Git diff 内容（例如 git diff --cached、git diff HEAD）
• 来自 .cursorrules 或 .cursor/rules 的仓库规则

返回包含置信度评分和解释的详细违规报告。

适用于：

• 提交前代码质量检查
• 确保符合团队编码标准
• 在代码审查前发现规则违规

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

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

根据功能需求为 AI 驱动的应用程序生成结构化的提示模板。

• 将用户需求转化为优化的提示模板
• 返回结构化模板和定义所需输入参数的上下文模式
• 示例：“创建一个按年龄和主题生成睡前故事的提示模板”

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

   • 首先使用 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 在主分支上的构建失败”

2. 使用 CircleCI URL：

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

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

   • 通过提供工作区根目录、git 远程 URL 和分支名称从本地工作区运行
   • 示例：“查找我当前分支上最新的失败流水线”

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

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

检索 CircleCI 作业的测试元数据，让您无需离开 IDE 即可分析测试结果。此工具有三种使用方式：

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

   • 示例：“获取 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 在主分支上的最新流水线状态”

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 在主分支上的制品”

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

   • 首先使用 list_followed_projects 获取您的项目，然后：
   • 示例：“为 my-project 在主分支上运行评估测试”

2. 使用 CircleCI URL：

   • 项目 URL、流水线 URL、工作流 URL 或作业 URL
   • 示例：“为 https://app.circleci.com/pipelines/gh/organization/project/123 运行评估测试”

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

   • 通过提供工作区根目录、git 远程 URL 和分支名称从本地工作区运行

该工具接受提示模板文件，并返回一个用于监控触发流水线的 URL。

[!NOTE] 如果项目有多个流水线定义，该工具将返回可用流水线列表供您选择。

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

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

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

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