CircleCI MCP 服务器

将你的 AI 助手连接到 CircleCI 数据，通过自然语言调试构建失败、分析测试结果并优化流水线。

MCP 概述
MCP 功能一览
开始
可用工具
了解更多

AI 工具的 CI/CD 上下文

CircleCI MCP Server 让 AI 工具真正读懂你的构建系统，使 Cursor、Claude Code、Windsurf 等工具能够直接理解并使用你的 CI/CD 数据。这种轻量级标准基于模型上下文协议（MCP）构建，允许基于 LLM 的代理从外部系统获取结构化数据。

通过连接 CircleCI MCP 服务器，代理可以实时掌握以下信息：

构建日志和测试输出
流水线状态
近期配置变更
工作流程性能指标

这意味着，你不再需要在任务日志或控制台界面中来回查找，只需直接提问：

why did my last build fail?

并获得解决问题所需的完整信息，在不中断工作节奏的情况下快速继续推进。

将构建数据转化为行动

安装后，MCP服务器通过自然语言访问您的CI/CD数据。基于LLM的工具可以：

诊断失败的构建
获取结构化错误摘要和日志。

追踪失败原因到最近变更
将回归问题关联到提交、差异或工作流。

发现不稳定测试（
从测试历史中识别波动模式。

提供改进建议
根据上下文提出配置或执行时间优化方案。

把 CI 数据导入编辑器
使用 LLM 工具分析构建，无需切换标签页。

通过同时访问代码和构建上下文，这些工具可以帮助你更快修复 Bug，更自信地发布变更，并专注于最重要的工作。

开始使用 MCP

CircleCI MCP Server 在本地运行，可与多种编辑器和 LLM 开发工具集成。

以下是即用型配置示例，帮助您在首选环境中安装 MCP Server。

前提条件

在设置 IDE 之前，请确保您已具备以下条件：

CircleCI 个人 API 令牌（PAT）：
- 前往 用户设置 > 个人 API 令牌
- 点击 创建新令牌
- 复制并妥善保存——您将在设置过程中将其用作 CIRCLECI_TOKEN
使用 NPX 安装：
- pnpm 包管理器
- Node.js 版本 ≥ 18.0.0
使用 Docker 安装：
- Docker

配置说明

Cursor

使用 NPX：


{
  "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"
      }
    }
  }
}

使用 Docker：


{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CIRCLECI_TOKEN",
        "-e", "CIRCLECI_BASE_URL",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com"
      }
    }
  }
}

Cursor 设置文档

VS Code

使用 NPX：


{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API 令牌",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI 基础 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}"
      }
    }
  }
}

使用 Docker：


{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API 令牌",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI 基础 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}"
      }
    }
  }
}

VS Code 设置文档

Claude Desktop

使用 NPX：


{
  "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"
      }
    }
  }
}

使用 Docker：


{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CIRCLECI_TOKEN",
        "-e", "CIRCLECI_BASE_URL",
        "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 Desktop 设置文档

Claude Code

使用 NPX：


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

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

Claude Code 设置文档

Windsurf

使用 NPX：


{
  "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"
      }
    }
  }
}

使用 Docker：


{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CIRCLECI_TOKEN",
        "-e", "CIRCLECI_BASE_URL",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com"
      }
    }
  }
}

Windsurf 设置文档

Amazon Q Developer / Kiro

前提条件：

CircleCI 个人 API 令牌
NPX：Node.js >= v18 及 pnpm

配置文件：
Amazon Q Developer 和 Kiro CLI 以 JSON 格式存储 MCP 客户端配置。配置路径因工具不同而有所差异：

Amazon Q Developer：
- 本地：.amazonq/agents/default.json
- 全局：~/.aws/amazonq/agents/default.json

Kiro CLI：
- 工作区：.kiro/settings/mcp.json
- 全局：~/.kiro/settings/mcp.json

上述 Amazon Q Developer 路径适用于默认代理。如果使用自定义代理，请将 MCP Server 配置添加到对应代理的配置文件中。

两者均为可选。若两者均存在，配置将从两处读取。若同一服务器在两处均有定义，则以本地/工作区配置为准。

使用 NPX（本地 MCP Server）：

将以下内容添加到您的配置文件中：

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // 可选，仅本地部署时需要
      },
      "timeout": 60000
    }
  }
}

使用自托管远程 MCP Server：

创建一个包装脚本（例如 circleci-remote-mcp.sh）：

#!/bin/bash
export CIRCLECI_TOKEN="your-circleci-token"
npx mcp-remote http://your-circleci-remote-mcp-server-endpoint:8000/mcp --allow-http

赋予执行权限：

chmod +x circleci-remote-mcp.sh

添加远程服务器：

通过 Kiro CLI：

kiro-cli mcp add --name circleci --command "/full/path/to/circleci-remote-mcp.sh"

通过 Amazon Q MCP 配置界面：

选择全局或本地范围
输入服务器名称（例如 circleci-remote-mcp）
设置传输协议：stdio
设置命令：包装脚本路径（例如 /full/path/to/circleci-remote-mcp.sh）
保存配置

通过 Smithery 安装


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

可用工具

从加速 AI 驱动的开发到编排智能体工作流，MCP Server 提供的每项工具都为 AI 开发者提供结构化的 CI/CD 上下文，助力实现更快速、更可靠的发布周期。

工具	用途
`config_helper`	在配置问题影响流水线之前提前修复
`create_prompt_template`	生成支持一致 AI 行为的提示词模板
`find_flaky_tests`	识别并排查不稳定测试
`get_build_failure_logs`	更快速地调试和解决构建失败问题
`get_job_test_results`	分析并修复测试失败及性能问题
`get_latest_pipeline_status`	监控流水线健康状态并采取相应措施
`list_followed_projects`	查找您关注的项目及其 `projectSlug`
`recommend_prompt_template_tests`	测试并提升提示词可靠性
`rerun_workflow`	从头或从失败的作业重新运行工作流
`run_pipeline`	在编辑器中直接触发构建
`run_rollback_pipeline`	通过单条命令回滚有问题的部署

了解更多

立即开始使用 CircleCI MCP Server，浏览示例，或及时了解平台最新动态：

项目仓库 – 源代码、Issue 及贡献指南。
MCP Cookbook – 提示词示例与工具使用模式。
博客文章：CircleCI MCP Server 介绍 – 设计背景与使用场景。
CircleCI 更新日志 – 查看最新的平台更新与功能发布。

概览

功能

集成

角色

使用场景

公司规模

开发者

探索

社区

优势

对比

公司

概览

功能

集成

角色

使用场景

公司规模

开发者

探索

社区

优势

对比

公司

CircleCI MCP 服务器

AI 工具的 CI/CD 上下文

将构建数据转化为行动

开始使用 MCP

前提条件

配置说明

可用工具

了解更多