CircleCI MCP服务器项目介绍

项目概述

CircleCI MCP服务器是专为模型上下文协议(MCP)设计的专业服务器实现，旨在集成CircleCI的开发工作流程。该项目作为CircleCI基础设施与模型上下文协议之间的桥梁，提供增强的AI驱动开发体验。

该服务器让AI工具如Cursor、Claude Code、Windsurf等能够理解您的构建系统。它基于模型上下文协议(MCP)构建，这是一个轻量级标准，允许LLM驱动的代理从外部系统获取结构化数据。

核心功能

主要工具和功能

1. get_build_failure_logs

检索CircleCI构建的详细失败日志。该工具支持两种使用方式：

使用CircleCI URL:

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

使用本地项目上下文:

通过提供以下信息从本地工作空间工作：
- 工作空间根路径
- Git远程URL
- 分支名称
示例: "查找我当前分支上最新的失败流水线"

返回的格式化日志包括：

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

2. find_flaky_tests

通过分析测试执行历史识别CircleCI项目中的不稳定测试。支持两种使用方式：

使用CircleCI项目URL:

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

使用本地项目上下文:

通过提供工作空间根路径和Git远程URL从本地工作空间工作

返回不稳定测试的详细信息，包括：

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

3. get_latest_pipeline_status

检索给定分支最新流水线的状态。工具返回最新流水线的格式化状态：

工作流程名称及其当前状态
每个工作流程的持续时间
创建和完成时间戳
整体流水线健康状况

示例输出：

--- 
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

4. get_job_test_results

检索CircleCI作业的测试元数据，允许您在不离开IDE的情况下分析测试结果。

返回详细的测试结果信息：

所有测试的摘要（总数、成功、失败）
失败测试的详细信息，包括：
- 测试名称和类
- 文件位置
- 错误消息
- 运行时持续时间
带有时间信息的成功测试列表

5. config_helper

协助CircleCI配置任务，提供指导和验证。该工具帮助您：

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

提供：

详细的验证结果
配置建议

6. create_prompt_template

基于功能需求生成结构化提示模板，用于AI启用的应用程序。该工具：

将功能需求转换为结构化提示：
- 将用户需求转换为优化的提示模板
- 示例: "为按年龄和主题生成睡前故事创建提示模板"

7. recommend_prompt_template_tests

为提示模板生成测试用例，确保它们产生预期结果。

安装和配置

系统要求

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

支持的IDE和工具

Cursor IDE

将以下内容添加到您的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" // 可选 - 仅本地部署客户需要
      }
    }
  }
}

VS Code

在 .vscode/mcp.json 中安装CircleCI MCP服务器：

{
  // 💡 输入在首次服务器启动时提示，然后由VS Code安全存储
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}"
      }
    }
  }
}

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" // 可选 - 仅本地部署客户需要
      }
    }
  }
}

配置文件位置：

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

Claude Code

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

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

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" // 可选 - 仅本地部署客户需要
      }
    }
  }
}

自动安装

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

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

开发和贡献

本地开发设置

克隆仓库：

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

安装依赖：

pnpm install

构建项目：

pnpm build

使用MCP检查器进行开发

最简单的MCP服务器迭代方式是使用MCP检查器。

启动开发服务器：

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

在单独的终端中启动检查器：

pnpm inspector

配置环境：
- 在检查器UI的环境变量部分添加您的 CIRCLECI_TOKEN
- 令牌需要对您的CircleCI项目的读取权限
- 可选择设置您的CircleCI基础URL，默认为 https://circleci.com

测试

运行测试套件：

pnpm test

在开发期间以监视模式运行测试：

pnpm test:watch

应用场景

该工具特别适用于：

调试失败的构建
分析测试失败
调查部署问题
在不离开IDE的情况下快速访问构建日志
检查最新流水线的状态
识别测试套件中不可靠的测试
对测试改进做出数据驱动的决策

项目优势

CircleCI MCP服务器专为支持开发生命周期中的实际时刻而设计。无论您是在审查失败的构建、调试失败的部署，还是关注关键分支，它都能帮助您的助手在几秒钟内理解失败并建议修复方案——无需上下文切换。

通过集成这个MCP服务器，开发者可以：

使用自然语言与CircleCI交互
在熟悉的开发环境中获取构建信息
快速诊断和解决CI/CD问题
提高开发工作流程的效率

mcp-server-circleci