Submit Log in

CircleCI MCP Server

by CircleCI

Released Aug 6, 2026

3 views

v0.20.0

Apache-2.0

Repository Docs npm

Developer Tools

Summary

CircleCI's official MCP server: pull build failure logs, hunt flaky tests, validate config, trigger and rerun pipelines, and roll back - in natural language from your IDE.

Features

Fetch build failure logs and job test results
Detect flaky tests from execution history
Validate CircleCI config and get fix guidance
Trigger pipelines, rerun workflows and run rollbacks
Find underused resource classes to cut compute spend
Download CircleCI Usage API data
Self-managed remote deployment for shared team use

Installation

Set up this MCP server in your favorite AI agent — copy a ready-made configuration below.

Any MCP-compatible agent

Most agents (Claude, Cursor, Windsurf, VS Code, and more) read a standard mcpServers configuration.

Open your agent's MCP configuration file.
Merge the snippet below into it, filling in the environment variables with your own values.
Restart the agent — the "CircleCI MCP Server" tools will be available.

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "<your-circleci-personal-api-token>",
        "CIRCLECI_BASE_URL": "https://circleci.com"
      }
    }
  }
}

Claude Code

Add the server with a single CLI command.

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=<your-circleci-personal-api-token> -e CIRCLECI_BASE_URL=https://circleci.com -- npx -y @circleci/mcp-server-circleci@latest

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config).

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "<your-circleci-personal-api-token>",
        "CIRCLECI_BASE_URL": "https://circleci.com"
      }
    }
  }
}

Cursor

{
  "command": "npx",
  "args": [
    "-y",
    "@circleci/mcp-server-circleci@latest"
  ],
  "env": {
    "CIRCLECI_TOKEN": "<your-circleci-personal-api-token>",
    "CIRCLECI_BASE_URL": "https://circleci.com"
  }
}

Windsurf

{
  "command": "npx",
  "args": [
    "-y",
    "@circleci/mcp-server-circleci@latest"
  ],
  "env": {
    "CIRCLECI_TOKEN": "<your-circleci-personal-api-token>"
  }
}

VS Code

{
  "command": "npx",
  "args": [
    "-y",
    "@circleci/mcp-server-circleci@latest"
  ],
  "env": {
    "CIRCLECI_TOKEN": "<your-circleci-personal-api-token>"
  }
}

Description

The CircleCI MCP Server puts your CI pipeline where your agent can read it. Instead of tabbing to the CircleCI web app to work out why a build went red, you ask in the editor and the agent fetches the failure logs, the test results and the config guidance it needs to propose a fix.

Tools

get_build_failure_logs - detailed failure logs from a build
get_latest_pipeline_status - status of the latest pipeline for a branch
get_job_test_results - test metadata and results for a job
find_flaky_tests - identify flaky tests from execution history (optionally written to a directory via FILE_OUTPUT_DIRECTORY)
config_helper - validate a CircleCI config and get guidance on it
run_pipeline - trigger a pipeline
rerun_workflow - rerun a workflow from the start or from the failed job
run_rollback_pipeline - trigger a rollback for a project
list_followed_projects, list_artifacts, list_component_versions
find_underused_resource_classes - spot jobs paying for more compute than they use
download_usage_api_data - pull data from the CircleCI Usage API

Running it

The usual setup is npx-based and needs Node.js 18 or newer plus a CircleCI personal API token in CIRCLECI_TOKEN; CIRCLECI_BASE_URL points at your CircleCI instance. A Docker image is available as a fallback. For teams, the project documents a self-managed remote server you deploy once (Kubernetes or Docker) with either per-developer or shared tokens, instead of every engineer running a local copy.

Configuration is documented for Cursor, Windsurf, VS Code Copilot, Claude, Amazon Q Developer (~/.aws/amazonq/mcp.json globally or .amazonq/mcp.json per workspace) and any other MCP-compatible client. Telemetry is described in the README. Apache-2.0 licensed and maintained by CircleCI-Public.

Covered in the Weekly

Onei AI Weekly #2 — August 10, 2026

Related MCP Servers

MCP: Arm MCP Server

by Arm

New

Arm's official MCP server for porting and tuning software on Arm — semantic docs search, codebase migration scanning, container architecture checks and LLVM-MCA assembly analysis.

Developer Tools

MCP: AntV Chart MCP

by AntV

New

Official AntV MCP server that turns a description of your data into a rendered chart — 26 visualization types from bar and line to sankey, mind-map, fishbone and geographic maps.

Developer Tools Databases & Data

MCP: Headroom

by Headroom Labs

New

Context-compression MCP server that shrinks tool outputs, logs, files and RAG chunks before they reach the model, cutting 60-95% of tokens on JSON payloads.

Developer Tools

MCP: Engram

by Gentleman Programming

New

Persistent memory for coding agents as a single Go binary — SQLite and FTS5 behind MCP, an HTTP API, a CLI and a TUI, with no Node, Python or Docker required.

Developer Tools

Browse all MCP servers →