CircleCI 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，更自信地发布变更，并专注于最重要的工作。

Recommended setup

For local editors — use the CircleCI CLI. The MCP server is built directly into the CLI, which is the recommended way to connect Cursor, VS Code, Claude Desktop, and similar tools to CircleCI.

For web-hosted agents like Claude.ai, or if company policy prefers — use the hosted MCP server, which connects via OAuth2 and requires no local install.

Both can be active at the same time.

Note for original local MCP users: Our original local MCP server is in maintenance mode and is no longer recommended. If you need to stay on the original server for now, use version 0.19.0 or later. Installs that use the @latest tag pick this up automatically; if you pin a specific version, point your configuration at @circleci/mcp-server-circleci@0.19.0.

开始使用 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 上下文

将构建数据转化为行动

Recommended setup

开始使用 MCP

前提条件

配置说明

可用工具

了解更多