Submit Log in

CircleCI MCP Server

by CircleCI

v0.20.0

Apache-2.0

Repository Docs npm

Developer Tools

circlecici-cdpipelinesflaky-testsdevops

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.

Related MCP Servers

MCP: Azure DevOps MCP Server

by Microsoft

New

Microsoft's official MCP server for Azure DevOps - work items, repos, pipelines, wikis, test plans and iterations, reachable from any MCP client in plain language.

Developer Tools