CircleCI MCP 服务器

模型上下文协议 (MCP) 是一种新的标准化协议，用于管理大型语言模型（LLMs）与外部系统之间的上下文。在这个仓库中，我们为 CircleCI 提供了一个 MCP 服务器。

这使得你可以使用 Cursor IDE 或任何 MCP 客户端，通过自然语言来完成 CircleCI 的操作，例如：

• 找到我分支上最新的失败流水线并获取日志
  https://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide

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

要求

• pnpm 包管理器 - 了解更多
• Node.js >= v18.0.0
• CircleCI API 令牌 - 你可以通过 CircleCI 生成一个。了解更多 或者 点击这里 快速访问。

安装

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude Desktop 的 CircleCI MCP 服务器：

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

Cursor

将以下内容添加到你的 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" // Optional - required for on-prem customers only
      }
    }
  }
}

有关如何使用 MCP 服务器和 cursor 的更多信息，请参见以下指南：
https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers

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" // Optional - required for on-prem customers only
      }
    }
  }
}

要找到/创建此文件，首先打开你的 Claude 桌面设置。然后在设置面板左侧栏中点击“开发者”，再点击“编辑配置”。

这将在以下位置创建一个配置文件：

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

有关如何使用 MCP 服务器和 Claude Desktop 的更多信息，请参见以下指南：
https://modelcontextprotocol.io/quickstart/user

Claude Code

安装 Claude Code 后，运行以下命令：

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

有关如何使用 MCP 服务器和 Claude Code 的更多信息，请参见以下指南：
https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp

VS Code

在 settings.json 中的 mcp -> servers 下添加 MCP 服务器：

"circleci-mcp-server": {
  "command": "npx",
  "args": ["-y", "@circleci/mcp-server-circleci"],
  "env": {
    "CIRCLECI_TOKEN": "your-circleci-token",
    "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
  }
}

有关如何使用 MCP 服务器和 VS Code 的更多信息，请参见以下指南：
https://code.visualstudio.com/docs/copilot/chat/mcp-servers

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" // Optional - required for on-prem customers only
      }
    }
  }
}

请参阅以下指南以获取有关将 MCP 服务器与 windsurf 结合使用的更多信息：
https://docs.windsurf.com/windsurf/mcp

功能

支持的工具

• get_build_failure_logs

  从 CircleCI 构建中检索详细的失败日志。此工具可以通过两种方式使用：

  1. 使用 CircleCI URL：

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

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

     • 通过提供以下信息在您的本地工作空间中工作：
       • 工作区根路径
       • Git 远程 URL
       • 分支名称
     • 示例："在我的当前分支上找到最新的失败管道"

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

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

  这对于以下情况特别有用：

  • 调试失败的构建
  • 分析测试失败
  • 调查部署问题
  • 在不离开 IDE 的情况下快速访问构建日志

• find_flaky_tests

  通过分析测试执行历史来识别您 CircleCI 项目中的不稳定测试。这利用了此处描述的不稳定测试检测功能：https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detection

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

  1. 使用 CircleCI 项目 URL：

     • 直接从 CircleCI 提供项目 URL
     • 示例："在 https://app.circleci.com/pipelines/github/org/repo 中查找不稳定测试"

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

     • 通过提供以下信息在您的本地工作空间中工作：
       • 工作区根路径
       • Git 远程 URL
     • 示例："在我的当前项目中查找不稳定测试"

  该工具返回关于不稳定测试的详细信息，包括：

  • 测试名称和文件位置
  • 失败消息和上下文

  这有助于您：

  • 识别测试套件中的不可靠测试
  • 获取关于测试失败的详细上下文
  • 基于数据做出关于测试改进的决策

• config_helper

  通过提供指导和验证来帮助进行 CircleCI 配置任务。此工具可以帮助您：

  1. 验证 CircleCI 配置：
     • 检查您的 .circleci/config.yml 是否存在语法和语义错误
     • 示例："验证我的 CircleCI 配置"

  该工具提供：

  • 详细的验证结果
  • 配置建议

  这有助于您：

  • 在推送之前发现配置错误
  • 学习 CircleCI 配置的最佳实践
  • 解决配置问题
  • 正确实现 CircleCI 功能

开发

入门

1. 克隆仓库：

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

2. 安装依赖项：

   pnpm install
   

3. 构建项目：

   pnpm build
   

使用 MCP Inspector 开发

迭代MCP服务器最简单的方法是使用MCP检查器。您可以在 https://modelcontextprotocol.io/docs/tools/inspector 了解更多关于MCP检查器的信息。

1. 启动开发服务器：

   pnpm watch # 保持此命令在一个终端中运行
   

2. 在另一个终端中，启动检查器：

   pnpm inspector
   

3. 配置环境：

   • 在检查器UI的环境变量部分添加您的CIRCLECI_TOKEN
   • 该令牌需要对您的CircleCI项目具有读取权限
   • 可选地，您可以设置您的CircleCI基础URL。默认为 https//circleci.com

测试

• 运行测试套件：

  pnpm test
  

• 在开发过程中以监视模式运行测试：

  pnpm test:watch
  

有关更详细的贡献指南，请参阅 CONTRIBUTING.md