mcp-server-circleci

CircleCI MCP 服务器

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

这使您可以使用 Cursor IDE、Windsurf、Copilot 或任何 MCP 支持的客户端，使用自然语言通过 CircleCI 完成任务，例如：

• Find the latest failed pipeline on my branch and get logshttps://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

要求

• CircleCI API 令牌 - 您可以通过 CircleCI 生成一个。了解更多或点击此处快速访问。

对于 NPX 安装：

• pnpm 包管理器 -了解更多
• Node.js >= v18.0.0

对于 Docker 安装：

• Docker -了解更多

安装

光标

使用 NPX

将以下内容添加到您的游标 MCP 配置中：

使用 Docker

将以下内容添加到您的游标 MCP 配置中：

VS 代码

使用 NPX

要在.vscode/mcp.json中为 VS Code 安装 CircleCI MCP 服务器：

使用 Docker

使用 Docker 在.vscode/mcp.json中安装 CircleCI MCP Server for VS Code：

克劳德桌面

使用 NPX

将以下内容添加到您的 claude_desktop_config.json：

使用 Docker

将以下内容添加到您的 claude_desktop_config.json：

要查找/创建此文件，首先打开 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

克劳德·科德

使用 NPX

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

使用 Docker

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

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

风帆冲浪

使用 NPX

将以下内容添加到您的 windsurf mcp_config.json：

使用 Docker

将以下内容添加到您的 windsurf mcp_config.json：

有关使用 MCP 服务器和 windsurf 的更多信息，请参阅以下指南： https://docs.windsurf.com/windsurf/mcp

通过 Smithery 安装

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

特征

支持的工具

• get_build_failure_logs从 CircleCI 构建中检索详细的失败日志。此工具有三种使用方式：
  1. 使用项目 Slug 和 Branch（推荐的工作流程）：
     • 首先，列出您可用的项目：
       • 使用 list_followed_projects 工具获取您的项目
       • 例如：“列出我的 CircleCI 项目”
       • 然后选择与之关联的 projectSlug 项目
       • 例如：“让我们使用我的项目”
     • 然后请求检索特定分支的构建失败日志：
       • 示例：“获取主分支上我的项目的构建失败信息”
  2. 使用 CircleCI URL：
     • 直接提供失败的作业 URL 或管道 URL
     • 示例：“从https://app.circleci.com/pipelines/github/org/repo/123获取日志”
  3. 使用本地项目上下文：
     • 通过提供以下内容从您的本地工作区工作：
       • 工作区根路径
       • Git 远程 URL
       • 分支机构名称
     • 示例：“查找当前分支上最新的失败管道”

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

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

  这对于以下情况尤其有用：

  • 调试失败的构建
  • 分析测试失败
  • 调查部署问题
  • 无需离开 IDE 即可快速访问构建日志
• find_flaky_tests通过分析测试执行历史记录，识别 CircleCI 项目中的不稳定测试。这利用了此处描述的不稳定测试检测功能： https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detection此工具有三种使用方式：
  1. 使用 Project Slug（推荐工作流程）：
     • 首先，列出您可用的项目：
       • 使用 list_followed_projects 工具获取您的项目
       • 例如：“列出我的 CircleCI 项目”
       • 然后选择与之关联的 projectSlug 项目
       • 例如：“让我们使用我的项目”
     • 然后请求检索不稳定的测试：
       • 例如：“获取我的项目的不稳定测试”
  2. 使用 CircleCI 项目 URL：
     • 直接从 CircleCI 提供项目 URL
     • 示例：“在https://app.circleci.com/pipelines/github/org/repo中查找不稳定的测试”
  3. 使用本地项目上下文：
     • 通过提供以下内容从您的本地工作区工作：
       • 工作区根路径
       • Git 远程 URL
     • 例如：“查找当前项目中的不稳定测试”

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

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

  这可以帮助您：

  • 识别测试套件中不可靠的测试
  • 获取有关测试失败的详细背景信息
  • 做出有关测试改进的数据驱动决策
• get_latest_pipeline_status检索给定分支的最新管道状态。此工具有三种使用方式：
  1. 使用项目 Slug 和 Branch（推荐的工作流程）：
     • 首先，列出您可用的项目：
       • 使用 list_followed_projects 工具获取您的项目
       • 例如：“列出我的 CircleCI 项目”
       • 然后选择与之关联的 projectSlug 项目
       • 例如：“让我们使用我的项目”
     • 然后要求检索特定分支的最新管道状态：
       • 示例：“获取主分支上我的项目的最新管道状态”
  2. 使用 CircleCI 项目 URL：
     • 直接从 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

  这对于以下情况尤其有用：

  • 检查最新管道的状态
  • 获取特定分支的最新管道状态
  • 无需离开 IDE 即可快速检查最新管道的状态
• get_job_test_results检索 CircleCI 作业的测试元数据，让您无需离开 IDE 即可分析测试结果。此工具有三种使用方式：
  1. 使用项目 Slug 和 Branch（推荐的工作流程）：
     • 首先，列出你可用的项目：
       • 使用 list_followed_projects 工具获取您的项目
       • 例如：“列出我的 CircleCI 项目”
       • 然后选择与之关联的 projectSlug 项目
       • 例如：“让我们使用我的项目”
     • 然后要求检索特定分支的测试结果：
       • 示例：“获取主分支上我的项目的测试结果”
  2. 使用 CircleCI URL：
     • 提供以下任意格式的 CircleCI 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 ”
     • 示例：“获取https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def的测试结果”
  3. 使用本地项目上下文：
     • 通过提供以下内容从您的本地工作区工作：
       • 工作区根路径
       • Git 远程 URL
       • 分支机构名称
     • 示例：“获取主分支上当前项目的测试结果”

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

  • 所有测试的摘要（总计、成功、失败）
  • 有关失败测试的详细信息包括：
    • 测试名称和类别
    • 文件位置
    • 错误消息
    • 运行时间
  • 包含时间信息的成功测试列表
  • 按测试结果过滤

  这对于以下情况尤其有用：

  • 无需访问 CircleCI Web UI 即可快速分析测试失败
  • 识别测试失败的模式
  • 查找可能需要优化的慢速测试
  • 检查整个项目的测试覆盖率
  • 解决不稳定测试问题

  注意：该工具要求您在 CircleCI 配置中正确配置测试元数据。有关设置测试元数据收集的更多信息，请参阅： https ://circleci.com/docs/collect-test-data/

• config_helper通过提供指导和验证来协助完成 CircleCI 配置任务。此工具可帮助您：
  1. 验证 CircleCI 配置：
     • 检查你的 .circleci/config.yml 是否存在语法和语义错误
     • 示例：“验证我的 CircleCI 配置”

  该工具提供：

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

  这可以帮助您：

  • 推送之前捕获配置错误
  • 了解 CircleCI 配置最佳实践
  • 解决配置问题
  • 正确实现 CircleCI 功能
• create_prompt_template根据功能需求，帮助为支持 AI 的应用程序生成结构化的提示模板。此工具：
  1. 将功能需求转换为结构化提示：
     • 将用户需求转化为优化的提示模板
     • 示例：“创建一个按年龄和主题生成睡前故事的提示模板”

  该工具提供：

  • 结构化的提示模板
  • 定义所需输入参数的上下文模式

  这可以帮助您：

  • 为人工智能应用程序创建有效的提示
  • 标准化输入参数以获得一致的结果
  • 构建强大的 AI 驱动功能
• recommend_prompt_template_tests为提示模板生成测试用例，以确保其产生预期结果。此工具：
  1. 提供提示模板的测试用例：
     • 根据提示模板和上下文模式创建不同的测试场景
     • 示例：“为我的睡前故事提示模板生成测试”

  该工具提供：

  • 一系列推荐的测试用例
  • 多种参数组合来测试模板鲁棒性

  这可以帮助您：

  • 验证提示模板功能
  • 确保 AI 对输入做出一致的响应
  • 识别边缘情况和潜在问题
  • 提升整体人工智能应用质量
• list_followed_projects列出用户在 CircleCI 上关注的所有项目。此工具：
  1. 检索并显示项目：
     • 显示用户有权访问和关注的所有项目
     • 为每个条目提供项目名称和 projectSlug
     • 例如：“列出我的 CircleCI 项目”

  该工具返回项目的格式化列表，示例输出：

  Projects followed: 1. my-project (projectSlug: gh/organization/my-project) 2. another-project (projectSlug: gh/organization/another-project)

  这对于以下情况尤其有用：

  • 确定哪些 CircleCI 项目可供您使用
  • 获取其他 CircleCI 工具所需的 projectSlug
  • 选择后续操作的项目

  注意：许多其他 CircleCI 工具都需要 projectSlug（不是项目名称），并且将在选择项目后用于这些工具调用。

• run_pipeline触发管道运行。此工具有三种使用方式：
  1. 使用项目 Slug 和 Branch（推荐的工作流程）：
     • 首先，列出你可用的项目：
       • 使用 list_followed_projects 工具获取您的项目
       • 例如：“列出我的 CircleCI 项目”
       • 然后选择与之关联的 projectSlug 项目
       • 例如：“让我们使用我的项目”
     • 然后要求针对特定分支运行管道：
       • 示例：“在主分支上运行 my-project 的管道”
  2. 使用 CircleCI URL：
     • 提供以下任意格式的 CircleCI 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 ”
       • 包含分支的项目 URL：“ https://app.circleci.com/projects/github/org/repo?branch=main ”
     • 示例：“运行https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def的管道”
  3. 使用本地项目上下文：
     • 通过提供以下内容从您的本地工作区工作：
       • 工作区根路径
       • Git 远程 URL
       • 分支机构名称
     • 示例：“在主分支上运行我当前项目的管道”

  该工具返回一个链接来监视管道的执行情况。

  这对于以下情况尤其有用：

  • 无需访问 CircleCI Web UI 即可快速运行管道
  • 从特定分支运行管道

发展

入门

1. 克隆存储库：
   git clone https://github.com/CircleCI-Public/mcp-server-circleci.git cd mcp-server-circleci
2. 安装依赖项：
   pnpm install
3. 构建项目：
   pnpm build

构建 Docker 容器

您可以使用以下方式在本地构建 Docker 容器：

这将创建一个标记为circleci:mcp-server-circleci的 Docker 镜像，您可以将其与任何 MCP 客户端一起使用。

运行容器：

使用 MCP Inspector 进行开发

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

1. 启动开发服务器：
   pnpm watch # Keep this running in one terminal
2. 在单独的终端中，启动检查器：
   pnpm inspector
3. 配置环境：
   • 将您的CIRCLECI_TOKEN添加到检查器 UI 中的环境变量部分
   • 令牌需要对您的 CircleCI 项目的读取权限
   • 您也可以设置 CircleCI 基本 URL。默认为https//circleci.com

测试

• 运行测试套件：
  pnpm test
• 在开发期间以监视模式运行测试：
  pnpm test:watch

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