Development

CircleCI

BYCircleCI-Public★ 0GRADE B

Enable AI Agents to fix build failures from CircleCI.

⚡Config Installation

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "circleci": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-circleci"
      ]
    }
  }
}

* Note: Requires restart of Claude Desktop app.

View Source Code→

Deployment Infrastructure

OWN THIS SKILL?

Apply for the Verified Badge to boost trust and rankings.

Claim & Verify ($99)

Adoption Framework for CircleCI

Before installing any skill, define a clear objective and measurable outcome. A useful implementation question is: what workflow becomes faster, safer, or more reliable after this skill is active? If that answer is vague, delay rollout and tighten scope first.

For most teams, a low-risk pattern is preview-first rollout with one owner, one test scenario, and one rollback plan. Capture failures in a structured log so quality decisions are evidence-based. This is especially important for skills that touch file systems, external APIs, or automation chains with downstream side effects.

Define success metrics before installation.
Validate permission scope against policy boundaries.
Run one controlled pilot and document failure categories.
Promote only after acceptance checks pass consistently.

Pre-Deployment Review Questions

Use these questions before enabling the skill in shared environments. They reduce surprise incidents and make approval decisions consistent across teams.

What data can this skill read, write, or transmit by default?
Which failures are recoverable automatically and which require manual stop?
Do we have verifiable logs that prove safe behavior under load?
Is rollback tested, documented, and assigned to a clear owner?

If any answer is unclear, keep rollout in preview and close the gap before production use.

Editorial Review Snapshot

This listing includes an editorial QA layer in addition to automated rendering. Review status is based on documentation depth, content uniqueness, and operational safety signals from the upstream repository.

Last scan date: 2026-01-18
README depth: 972 words
Content diversity score: 0.31 (higher is better)
Template signal count: 0
Index status: Index eligible

Recommendation: Pilot in a bounded environment first. Confirm observability and ownership before promoting to shared workflows.

Skill Implementation Board

Actionable utility module for rollout decisions. Use the inputs below to choose a deployment path, then execute the checklist and record an output note.

Input: Security Grade

Input: Findings

Input: README Depth

972 words

Input: Index State

Eligible

Decision Trigger	Action	Expected Output
Input: risk band moderate, docs partial, findings 0	Run a preview pilot with fixed ownership and observability checkpoints.	Pilot can start with rollback checklist attached.
Input: page is index-eligible	Proceed with external documentation and team onboarding draft.	Reusable rollout runbook ready for team adoption.
Input: context tags/scenarios are missing	Define two concrete scenarios before broad rollout.	Clear scope definition before further deployment.

Execution Steps

Capture objective, owner, and rollback contact.
Run one preview pilot with fixed test scenario.
Record warning behavior and recovery evidence.
Promote only if pilot output matches expected threshold.

Output Template

skill=circleci
mode=B
pilot_result=pass|fail
warning_count=0
next_step=rollout|patch|hold

🛡️ Security Analysis

SCANNED: 2026-01-18

SCORE: 80/100

✅

Clean Scan Report

Our static analysis engine detected no common vulnerabilities (RCE, API Leaks, Unbounded FS).

DocumentationREADME.md

Note: The content below is automatically rendered from the repository's README file.

CircleCI MCP Server

Model Context Protocol (MCP) is a new, standardized protocol for managing context between large language models (LLMs) and external systems. In this repository, we provide an MCP Server for CircleCI.

This lets you use Cursor IDE, Windsurf, Copilot, or any MCP supported Client, to use natural language to accomplish things with CircleCI, e.g.:

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

Requirements

CircleCI Personal API Token - you can generate one through the CircleCI. Learn more or click here for quick access.

For NPX installation:

pnpm package manager - Learn more
Node.js >= v18.0.0

For Docker installation:

Docker - Learn more

Installation

Cursor

Using NPX in a local MCP Server

Add the following to your cursor MCP config:

{
  "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" // Optional - required for on-prem customers only
      }
    }
  }
}

Using Docker in a local MCP Server

Add the following to your cursor MCP config:

{
  "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" // Optional - required for on-prem customers only
      }
    }
  }
}

Using a Self-Managed Remote MCP Server

Add the following to your cursor MCP config:

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

Using NPX in a local MCP Server

To install CircleCI MCP Server for VS Code in .vscode/mcp.json:

{
  // 💡 Inputs are prompted on first server start, then stored securely by VS Code.
  "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": {
    // https://github.com/ppl-ai/modelcontextprotocol/
    "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}"
      }
    }
  }
}

Using Docker in a local MCP Server

To install CircleCI MCP Server for VS Code in .vscode/mcp.json using Docker:

{
  // 💡 Inputs are prompted on first server start, then stored securely by VS Code.
  "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": {
    // https://github.com/ppl-ai/modelcontextprotocol/
    "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}"
      }
    }
  }
}

Using a Self-Managed Remote MCP Server

To install CircleCI MCP Server for VS Code in .vscode/mcp.json using a self-managed remote MCP server:

{
  "servers": {
    "circleci-mcp-server-remote": {
      "type": "sse",
      "url": "http://your-circleci-remote-mcp-server-endpoint:8000/mcp"
    }
  }
}

Claude Desktop

Using NPX in a local MCP Server

Add the following to your claude_desktop_config.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" // Optional - required for on-prem customers only
      }
    }
  }
}

To locate this file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop setup

Using Docker in a local MCP Server

Add the following to your claude_desktop_config.json:

{
  "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" // Optional - required for on-prem customers only
      }
    }
  }
}

To find/create this file, first open your claude desktop settings. Then click on "Developer" in the left-hand bar of the Settings pane, and then click on "Edit Config"

This will create a configuration file at:

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

See the guide below for more information on using MCP servers with Claude Desktop: https://modelcontextprotocol.io/quickstart/user

Using a Self-Managed Remote MCP Server

Create a wrapper script first

Create a script file such as '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

Make it executable:

chmod +x circleci-remote-mcp.sh

Then add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "circleci-remote-mcp-server": {
      "command": "/full/path/to/circleci-remote-mcp.sh"
    }
  }
}

To find/create this file, first open your Claude Desktop settings. Then click on "Developer" in the left-hand bar of the Settings pane, and then click on "Edit Config"

This will create a configuration file at:

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

See the guide below for more information on using MCP servers with Claude Desktop: https://modelcontextprotocol.io/quickstart/user

Claude Code

Using NPX in a local MCP Server

After installing Claude Code, run the following command:

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

Using Docker in a local MCP Server

After installing Claude Code, run the following command:

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

See the guide below for more information on using MCP servers with Claude Code: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp

Using Self-Managed Remote MCP Server

After installing Claude Code, run the following command:

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

See the guide below for more information on using MCP servers with Claude Code: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp

Windsurf

Using NPX in a local MCP Server

Add the following to your windsurf mcp_config.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" // Optional - required for on-prem customers only
      }
    }
  }
}

Using Docker in a local MCP Server

Add the following to your windsurf mcp_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci:mcp-ser

...(truncated)