CircleCI MCP Server

MCPAI代理

提供方 CircleCI-Public · 包名 mcp-remote

AI代理 stdio · 本地进程 Token 社区 / 第三方 Claude DesktopClaudeCursorWindsurf
查看接入方式

CircleCI MCP服务器是一个基于模型上下文协议(MCP)的工具,允许用户通过自然语言与CircleCI交互,提供CI/CD流程管理和自动化功能。

一句话选型结论

按资料字段整理

CircleCI MCP Server 属于AI代理类 MCP 服务器,stdio · 本地进程,Token,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接复制的远程端点配置。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权Token 部署方式支持远程部署
GitHub 星标 83 仓库热度,无公开仓库时显示未标注
工具数 17 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量17暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

CI/CD工具TypeScript混合部署自动化流程自然语言交互开发效率工具MCP协议

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
npx mcp-remote http://your-circleci-remote-mcp-server-endpoint:8000/mcp --allow-http

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    确认你的客户端支持远程端点,并拿到服务地址。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 17 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 17 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
CircleCI MCP Server当前 17 stdio · 本地进程 支持远程部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方CircleCI-Public上游标注的维护方 CircleCI-Public
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时mcp-remote · Node.js本地安装时用到的包标识与运行时
部署类型支持远程部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

24.7 KB
来自项目仓库与上游目录的原文,未做删改

CircleCI MCP服务器

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

使用Cursor、Windsurf、Copilot、Claude或任何兼容MCP的客户端,使用自然语言与CircleCI进行交互,而无需离开IDE。

工具

工具 说明
analyze_diff 根据游标规则分析git差异是否违规
config_helper 验证并获取CircleCI配置的指导
create_prompt_template 为AI应用程序生成结构化提示模板
download_usage_api_data 从CircleCI usage API下载使用数据
find_flaky_tests 通过分析测试执行历史来识别不稳定的测试
find_underused_resource_classes 查找计算资源未充分利用的工作
get_build_failure_logs 从CircleCI构建中检索详细的故障日志
get_job_test_results 检索CircleCI作业的测试元数据和结果
get_latest_pipeline_status 获取分支的最新管道的状态
list_artifacts 列出CircleCI作业生成的工件
list_component_versions 列出CircleCI组件的所有版本
list_followed_projects 列出您正在关注的所有CircleCI项目
recommend_prompt_template_tests 为提示模板生成测试用例
rerun_workflow 从开始或从失败的作业重新运行工作流
run_evaluation_tests 在CircleCI管道上运行评估测试
run_pipeline 触发管道运行
run_rollback_pipeline 触发项目的回滚

安装

Cursor

先决条件:

  • CircleCI个人API令牌 (了解更多)
  • NPX: Node.js>=v18 和 pnpm
  • Docker: 码头工人

在本地MCP服务器中使用NPX

将以下内容添加到您的Cursor MCP配置中:```json
{
"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",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}


> `CIRCLECI_BASE_URL` 是可选的,仅本地客户需要。
> `MAX_MCP_OUTPUT_LENGTH` 可选--MCP响应的最大输出长度(默认值:50000)。

#### 在本地MCP服务器中使用Docker

将以下内容添加到您的Cursor MCP配置中:```json
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"CIRCLECI_TOKEN",
"-e",
"CIRCLECI_BASE_URL",
"-e",
"MAX_MCP_OUTPUT_LENGTH",
"circleci/mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}

使用自我管理的远程MCP服务器

将以下内容添加到您的Cursor MCP配置中:```json
{
"inputs": [
{
"type": "promptString",
"id": "circleci-token",
"description": "CircleCI API Token",
"password": true
}
],
"servers": {
"circleci-mcp-server-remote": {
"url": "http://your-circleci-remote-mcp-server-endpoint:8000/mcp"
}
}
}


VS Code

**先决条件:**

- CircleCI个人API令牌 (了解更多)
- NPX: Node.js>=v18 和 pnpm
- Docker: 码头工人

#### 在本地MCP服务器中使用NPX

添加以下内容 `.vscode/mcp.json` 在您的项目中:```json
{
"inputs": [
{
"type": "promptString",
"id": "circleci-token",
"description": "CircleCI API Token",
"password": true
},
{
"type": "promptString",
"id": "circleci-base-url",
"description": "CircleCI Base 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}"
}
}
}
}

> 💡 首次启动服务器时会提示输入,然后由VS Code安全存储。

在本地MCP服务器中使用Docker

添加以下内容 .vscode/mcp.json 在您的项目中:```json
{
"inputs": [
{
"type": "promptString",
"id": "circleci-token",
"description": "CircleCI API Token",
"password": true
},
{
"type": "promptString",
"id": "circleci-base-url",
"description": "CircleCI Base 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}"
}
}
}
}


#### 使用自我管理的远程MCP服务器

添加以下内容 `.vscode/mcp.json` 在您的项目中:```json
{
"servers": {
"circleci-mcp-server-remote": {
"type": "sse",
"url": "http://your-circleci-remote-mcp-server-endpoint:8000/mcp"
}
}
}

Claude Desktop

先决条件:

  • CircleCI个人API令牌 (了解更多)
  • NPX: Node.js>=v18 和 pnpm
  • Docker: 码头工人

在本地MCP服务器中使用NPX

将以下内容添加到您的 claude_desktop_config.json:```json
{
"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",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}


#### 在本地MCP服务器中使用Docker

将以下内容添加到您的 `claude_desktop_config.json`:```json
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"CIRCLECI_TOKEN",
"-e",
"CIRCLECI_BASE_URL",
"-e",
"MAX_MCP_OUTPUT_LENGTH",
"circleci/mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}

使用自我管理的远程MCP服务器

创建包装脚本(例如。 circleci-remote-mcp.sh):```bash

!/bin/bash

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


使其可执行:```bash
chmod +x circleci-remote-mcp.sh

然后将以下内容添加到您的 claude_desktop_config.json:```json
{
"mcpServers": {
"circleci-remote-mcp-server": {
"command": "/full/path/to/circleci-remote-mcp.sh"
}
}
}


要查找或创建配置文件,请打开Claude Desktop设置,单击 **开发者** 在左侧边栏中,然后单击 **编辑配置**配置文件位于:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- 窗户: `%APPDATA%\Claude\claude_desktop_config.json`

更多信息:https://modelcontextprotocol.io/quickstart/user

Claude Code

**先决条件:**

- CircleCI个人API令牌 (了解更多)
- NPX: Node.js>=v18 和 pnpm
- Docker: 码头工人

#### 在本地MCP服务器中使用NPX```bash
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest

在本地MCP服务器中使用Docker```bash

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


#### 使用自我管理的远程MCP服务器```bash
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx mcp-remote http://your-circleci-remote-mcp-server-endpoint:8000/mcp --allow-http

更多信息:https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up模型上下文协议mcp

Windsurf

先决条件:

  • CircleCI个人API令牌 (了解更多)
  • NPX: Node.js>=v18 和 pnpm
  • Docker: 码头工人

在本地MCP服务器中使用NPX

将以下内容添加到您的Windsurf mcp_config.json:```json
{
"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",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}


#### 在本地MCP服务器中使用Docker

将以下内容添加到您的Windsurf `mcp_config.json`:```json
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"CIRCLECI_TOKEN",
"-e",
"CIRCLECI_BASE_URL",
"-e",
"MAX_MCP_OUTPUT_LENGTH",
"circleci/mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}

使用自我管理的远程MCP服务器

将以下内容添加到您的Windsurf mcp_config.json:```json
{
"mcpServers": {
"circleci": {
"command": "npx",
"args": [
"mcp-remote",
"http://your-circleci-remote-mcp-server-endpoint:8000/mcp",
"--allow-http"
],
"disabled": false,
"alwaysAllow": []
}
}
}


更多信息:https://docs.windsurf.com/windsurf/mcp

Amazon Q Developer CLI

**先决条件:**

- CircleCI个人API令牌 (了解更多)
- NPX: Node.js>=v18 和 pnpm

Amazon Q Developer中的MCP客户端配置以JSON格式存储在名为的文件中 `mcp.json`支持两个级别的配置:

- **全球的:** `~/.aws/amazonq/mcp.json` --适用于所有工作区
- **工作区:** `.amazonq/mcp.json` --特定于当前工作区

如果两个文件都存在,则将合并它们的内容。如果发生冲突,则以工作区配置为准。

#### 在本地MCP服务器中使用NPX

编辑 `~/.aws/amazonq/mcp.json` 或创建 `.amazonq/mcp.json` 具有以下内容:```json
{
"mcpServers": {
"circleci-local": {
"command": "npx",
"args": [
"-y",
"@circleci/mcp-server-circleci@latest"
],
"env": {
"CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
},
"timeout": 60000
}
}
}

使用自我管理的远程MCP服务器

创建包装脚本(例如。 circleci-remote-mcp.sh):```bash

!/bin/bash

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


使其可执行并添加:```bash
chmod +x circleci-remote-mcp.sh
q mcp add --name circleci --command "/full/path/to/circleci-remote-mcp.sh"

Amazon Q Developer in the IDE

先决条件:

  • CircleCI个人API令牌 (了解更多)
  • NPX: Node.js>=v18 和 pnpm

在本地MCP服务器中使用NPX

编辑 ~/.aws/amazonq/mcp.json 或创建 .amazonq/mcp.json 具有以下内容:```json
{
"mcpServers": {
"circleci-local": {
"command": "npx",
"args": [
"-y",
"@circleci/mcp-server-circleci@latest"
],
"env": {
"CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
"CIRCLECI_BASE_URL": "https://circleci.com",
"MAX_MCP_OUTPUT_LENGTH": "50000"
},
"timeout": 60000
}
}
}


#### 使用自我管理的远程MCP服务器

创建包装脚本(例如。 `circleci-remote-mcp.sh`):```bash
#!/bin/bash
npx mcp-remote http://your-circleci-remote-mcp-server-endpoint:8000/mcp --allow-http

使其可执行,然后通过MCP配置UI添加它:

  1. 访问MCP配置UI
  2. 选择 + 符号
  3. 选择范围: 全球 或 本地
  4. 输入名称(例如。 circleci-remote-mcp)
  5. 选择传输协议: 标准
  6. 输入脚本的命令路径
  7. 点击 保存

Smithery

通过以下方式自动安装适用于Claude Desktop的CircleCI MCP服务器 铁匠铺:```bash
npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude


## 演示

Watch it in action

示例:“在我的分支上查找最新失败的管道并获取日志”
--看看 维基 更多示例。

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

## 工具详细信息

analyze_diff

根据游标规则分析git差异,以识别规则违规。

提供:

- **Git差异内容** (例如。 `git diff --cached`, `git diff HEAD`)
- **存储库规则** 从 `.cursorrules` 或 `.cursor/rules`

返回详细的违规报告,包括置信度评分和解释。

适用于:

- 预提交代码质量检查
- 确保与团队编码标准保持一致
- 在代码审查之前发现违反规则的行为

config_helper

通过提供指导和验证来协助CircleCI配置任务。

- 验证您的 `.circleci/config.yml` 语法和语义错误
- 提供详细的验证结果和配置建议
- 示例:“验证我的CircleCI配置”

create_prompt_template

根据功能要求为支持AI的应用程序生成结构化提示模板。

- 将用户需求转化为优化的提示模板
- 返回一个结构化模板和一个定义所需输入参数的上下文模式
- 示例:“创建按年龄和主题生成睡前故事的提示模板”

download_usage_api_data

从给定组织的CircleCI usage API下载使用情况数据。接受灵活的日期输入(例如,“2025年3月”或“上个月”)。仅限云功能。

**选项1:** 通过提供以下内容启动新的导出作业:

- `orgId`, `startDate`, `endDate` (最多32天), `outputDir`

**选项2:** 通过提供以下内容检查/下载现有的导出作业:

- `orgId`, `jobId`, `outputDir`

返回一个CSV文件,其中包含指定时间范围内的CircleCI使用数据。

> \[!注意\]
> 使用数据可以输入 `find_underused_resource_classes` 成本优化分析工具。

find_flaky_tests

通过分析测试执行历史记录来识别CircleCI项目中的不稳定测试。利用 片状测试检测功能 在CircleCI。

该工具有三种使用方式:

1. **使用Project Slug(推荐):**

- 先用 `list_followed_projects` 要获取您的项目,请执行以下操作:
- 示例:“为我的项目获取不稳定的测试”

1. **使用CircleCI项目URL:**

- 示例:“在中查找片状测试https://app.circleci.com/pipelines/github/org/repo"

1. **使用本地项目上下文:**

- 通过提供工作区根和git远程URL从本地工作区工作
- 示例:“在我当前的项目中查找不稳定的测试”

输出模式:

- **文本(默认):** 以文本格式返回片状测试详细信息
- **文件** (要求 `FILE_OUTPUT_DIRECTORY` env-var):创建一个包含零散测试详细信息的目录

find_underused_resource_classes

分析CircleCI使用数据CSV文件,以查找平均或最大CPU/RAM使用率低于给定阈值(默认值:40%)的作业。

提供从以下来源获得的CSV文件 `download_usage_api_data`.

返回按项目和工作流组织的未充分利用的作业的降价列表,这对于识别成本优化机会非常有用。

get_build_failure_logs

从CircleCI构建中检索详细的故障日志。该工具有三种使用方式:

1. **使用项目Slug和Branch(推荐):**

- 先用 `list_followed_projects` 要获取您的项目,请执行以下操作:
- 示例:“在主分支上获取我的项目的构建失败”

1. **使用CircleCI网址:**

- 直接提供失败的作业URL或管道URL
- 示例:“从以下位置获取日志https://app.circleci.com/pipelines/github/org/repo/123"

1. **使用本地项目上下文:**

- 通过提供工作区根、git远程URL和分支名称,在本地工作区工作
- 示例:“查找我当前分支上最新失败的管道”

该工具返回格式化的日志,包括:

- 作业名称
- 分步执行细节
- 故障消息和上下文

get_job_test_results

检索CircleCI作业的测试元数据,使您无需离开IDE即可分析测试结果。该工具有三种使用方式:

1. **使用项目Slug和Branch(推荐):**

- 示例:“在主分支上获取我的项目的测试结果”

1. **使用CircleCI URL:**

- 作业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`

1. **使用本地项目上下文:**

- 通过提供工作区根、git远程URL和分支名称,在本地工作区工作

工具返回:

- 所有测试的总结(总计、成功、失败)
- 失败测试的详细信息:名称、类、文件、错误消息、持续时间
- 成功测试的时间列表
- 按测试结果过滤

> \[!注意\]
> 必须在CircleCI配置中配置测试元数据。看 收集测试数据 有关设置说明。

get_latest_pipeline_status

检索给定分支的最新管道的状态。该工具有三种使用方式:

1. **使用项目Slug和Branch(推荐):**

- 示例:“在主分支上获取我的项目的最新管道的状态”

1. **使用CircleCI项目URL:**

- 示例:“获取最新管道的状态https://app.circleci.com/pipelines/github/org/repo"

1. **使用本地项目上下文:**

- 通过提供工作区根、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

list_artifacts

检索CircleCI作业生成的工件列表。该工具有三种使用方式:

  1. 使用项目Slug和Branch(推荐):
  • 先用 list_followed_projects 要获取您的项目,请执行以下操作:
  • 示例:“在主分支上列出我的项目的工件”
  1. 使用CircleCI URL:
  • 作业URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
  • 工作流URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
  • 管道URL: https://app.circleci.com/pipelines/gh/organization/project/123
  1. 使用本地项目上下文:
  • 通过提供工作区根、git远程URL和分支名称,在本地工作区工作

适用于:

  • 查找构建工件(二进制文件、报告、日志)的下载URL
  • 检查管道运行产生了哪些工件

list_component_versions

列出环境中特定CircleCI组件的所有版本。包括部署状态、提交信息和时间戳。

如果没有提供,该工具将提示您选择组件和环境。

适用于:

  • 确定当前使用的版本
  • 选择回滚操作的目标版本
  • 获取部署详细信息(管道、工作流、作业)

list_followed_projects

列出用户在CircleCI上关注的所有项目。

  • 显示您有权访问的所有项目及其 projectSlug
  • 示例:“列出我的CircleCI项目”

输出示例:```
Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)


> \[!注意\]
> 这 `projectSlug` (不是项目名称)是许多其他CircleCI工具所必需的。

recommend_prompt_template_tests

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

- 根据提示模板和上下文模式创建不同的测试场景
- 返回具有各种参数组合的推荐测试用例数组
- 示例:“为我的睡前故事提示模板生成测试”

rerun_workflow

从工作流开始或从失败的作业重新运行工作流。

返回新创建的工作流的ID和监视它的链接。

run_evaluation_tests

在CircleCI管道上运行评估测试(也称为“提示测试”)。生成适当的CircleCI配置,并使用它触发管道。

该工具有三种使用方式:

1. **使用项目Slug和Branch(推荐):**

- 先用 `list_followed_projects` 要获取您的项目,请执行以下操作:
- 示例:“在主分支上为我的项目运行评估测试”

1. **使用CircleCI URL:**

- 项目URL、工作流URL或作业URL
- 示例:“运行评估测试https://app.circleci.com/pipelines/gh/organization/project/123"

1. **使用本地项目上下文:**

- 通过提供工作区根、git远程URL和分支名称,在本地工作区工作

该工具接受提示模板文件,并返回一个URL来监视触发的管道。

> \[!注意\]
> 如果项目有多个管道定义,该工具将返回可用管道列表供您选择。

run_pipeline

触发管道运行。该工具有三种使用方式:

1. **使用项目Slug和Branch(推荐):**

- 示例:“在主分支上运行我的项目的管道”

1. **使用CircleCI URL:**

- 管道URL、工作流URL、作业URL或带分支的项目URL
- 示例:“运行管道https://app.circleci.com/pipelines/github/org/repo/123"

1. **使用本地项目上下文:**

- 通过提供工作区根、git远程URL和分支名称,在本地工作区工作

该工具返回一个链接以监视管道执行。

run_rollback_pipeline

触发CircleCI项目的回滚。该工具以交互方式引导您完成以下操作:

1. **项目选择** --列出以下项目供您选择
1. **环境选择** --列出可用环境(如果只有一个,则自动选择)
1. **组件选择** --列出可用组件(如果只有一个,则自动选择)
1. **版本选择** --显示可用版本;您选择回滚的目标
1. **回滚模式检测** --检查是否配置了回滚管道
1. **执行回滚** --两种选择:
- **管道回滚:** 触发回滚管道
- **工作流重新运行:** 使用其工作流ID重新运行以前的工作流
1. **确认** --执行前进行总结和确认

## 故障排除

Quick Fixes

**最常见的问题:**

1. **清除包缓存:**```bash
npx clear-npx-cache
npm cache clean --force
  1. 强制使用最新版本: 添加 @latest 到您的配置:```json
    "args": ["-y", "@circleci/mcp-server-circleci@latest"]

1. **完全重新启动IDE** (不仅仅是重新加载窗口)

Authentication Issues

- **无效的令牌错误:** 验证您的 `CIRCLECI_TOKEN` 在 个人API代币
- **权限错误:** 确保令牌具有对项目的读取权限
- **未加载环境变量:** 测试用 `echo $CIRCLECI_TOKEN` (Mac/Linux)或 `echo %CIRCLECI_TOKEN%` (Windows)

Connection and Network Issues

- **基本URL:** 确认 `CIRCLECI_BASE_URL` 是 `https://circleci.com`
- **企业网络:** 如果位于防火墙之后,请配置npm代理设置
- **防火墙阻止:** 检查安全软件是否阻止软件包下载

System Requirements

- **Node.js版本:** 确保>=18.0.0 `node --version`
- **更新Node.js:** 如果遇到兼容性问题,请考虑最新的LTS
- **包管理器:** 验证npm/pnpm是否正常工作: `npm --version`

IDE-Specific Issues

- **配置文件位置:** 仔细检查操作系统的路径
- **语法错误:** 验证配置文件中的JSON语法
- **控制台日志:** 检查IDE开发人员控制台是否存在特定错误
- **尝试其他IDE:** 在另一个受支持的编辑器中测试以隔离问题

Process Issues

**挂起进程——杀死现有的MCP进程:**```bash
# Mac/Linux:
pkill -f "mcp-server-circleci"

# Windows:
taskkill /f /im node.exe

端口冲突: 如果连接似乎被阻止,请重新启动IDE。

Advanced Debugging

  • 直接测试包: npx @circleci/mcp-server-circleci@latest --help
  • 详细日志记录: DEBUG=* npx @circleci/mcp-server-circleci@latest
  • Docker回退: 如果npx持续失败,请尝试安装Docker

还需要帮助吗?

  1. 检查 GitHub问题 对于类似的问题
  2. 报告问题时包括您的操作系统、节点版本和IDE
  3. 从IDE控制台共享相关错误消息

遥测

服务器支持OpenTetry指标来跟踪工具使用情况。要禁用遥测,请设置 DISABLE_TELEMETRY=true.

度量 描述
circleci.mcp.tool.invocations 工具调用计数
circleci.mcp.tool.duration_ms 执行时间(毫秒)
circleci.mcp.tool.errors 错误计数

发展

入门指南

  1. 克隆存储库:```bash
    git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
    cd mcp-server-circleci

1. 安装依赖项:```bash
pnpm install
  1. 构建项目:```bash
    pnpm build

## 构建Docker容器

您可以使用以下命令在本地构建Docker容器:```bash
docker build -t circleci:mcp-server-circleci .

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

要在本地运行容器,请执行以下操作:```bash
docker run --rm -i -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com circleci:mcp-server-circleci


要将容器作为自我管理的远程MCP服务器运行,请添加 `start=remote` 并可选择指定端口(默认值: `8000`):```bash
docker run --rm -i -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com -e start=remote -e port=8000 circleci:mcp-server-circleci

使用MCP Inspector进行开发

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

  1. 启动开发服务器:```bash
    pnpm watch # Keep this running in one terminal

1. 在单独的终端中,启动检查器:```bash
pnpm inspector
  1. 配置环境:
  • 添加您的 CIRCLECI_TOKEN 转到检查器UI中的“环境变量”部分
  • 令牌需要对您的CircleCI项目具有读取权限
  • 您可以选择设置CircleCI基本URL(默认为 https://circleci.com)

测试

  • 运行测试套件:```bash
    pnpm test

- 在开发过程中以监视模式运行测试:```bash
pnpm test:watch

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

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
CircleCI MCP Server 怎么安装?

在客户端按下面的安装命令接入:npx mcp-remote http://your-circleci-remote-mcp-server-endpoint:8000/mcp --allow-http。对应的包名是 mcp-remote。装完在客户端配置里引用同一个包或端点。

CircleCI MCP Server 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

CircleCI MCP Server 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

CircleCI MCP Server 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

CircleCI MCP Server 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、Windsurf、VS Code;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

CircleCI MCP Server 能提供哪些能力?

资料显示约 17 个工具;能力标签包括 自然语言交互、TypeScript、Claude。具体工具清单以官方文档为准。

CircleCI MCP Server 需要什么运行环境?

运行时为 Node.js;属于本地进程,需要在本机装好运行环境。

CircleCI MCP Server 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。