How to add CircleCI MCP Server to Claude Desktop

Official CircleCI MCP server: inspect and fix failed builds, query pipelines in natural language. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 15, 2026 · 230★ · stdio · apikey · official

Claude Desktop config for CircleCI MCP Server

npx -y @circleci/mcp-server-circleci

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

Setup steps

1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
2Paste the CircleCI MCP Server config below under the top-level "mcpServers" key.
3Fill in any placeholder secrets (API keys, paths) in the snippet.
4Save the file, then fully quit and reopen Claude Desktop.
5Open a chat and confirm CircleCI MCP Server's tools appear under the 🔌 tools menu.

Before you start

Node.js 18+ (run via npx) or Docker
A CircleCI account with at least one project building on CircleCI
A CircleCI Personal API Token from app.circleci.com/settings/user/tokens (passed via the CIRCLECI_TOKEN env var)
An MCP-compatible client: Cursor, VS Code, Claude Desktop, Claude Code, Windsurf, or Amazon Q Developer

What CircleCI MCP Server can do in Claude Desktop

get_build_failure_logs

Retrieve detailed logs from a failed build or job to diagnose the cause.

config_helper

Validate a .circleci/config.yml and get guidance on fixing configuration errors.

find_flaky_tests

Identify flaky tests across a project using execution history.

get_job_test_results

Pull test metadata and pass/fail outcomes for a CircleCI job.

get_latest_pipeline_status

Show the current pipeline state for a given branch.

run_pipeline

Trigger a pipeline run for a project/branch.

rerun_workflow

Re-run a workflow from the start or from failed jobs only.

run_rollback_pipeline

Trigger a rollback pipeline for a project.

Security

The CircleCI API token can read project configuration, environment variable names and build logs that may contain secrets; scope it to the minimum projects needed and treat it as sensitive.

CircleCI MCP Server + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the CircleCI MCP Server config there under the "mcpServers" key and restart the client.

Is CircleCI MCP Server safe to use with Claude Desktop?

The CircleCI API token can read project configuration, environment variable names and build logs that may contain secrets; scope it to the minimum projects needed and treat it as sensitive.

Is this the official CircleCI MCP server?

Yes. It is maintained by CircleCI under the CircleCI-Public GitHub org and published as @circleci/mcp-server-circleci.

How do I authenticate?

Create a Personal API Token in your CircleCI user settings and provide it via the CIRCLECI_TOKEN environment variable in your MCP client config.

Which clients are supported?

Cursor, VS Code, Claude Desktop, Claude Code, Windsurf, Amazon Q Developer, and other MCP-compatible clients. It also installs via Smithery.

View repo Full CircleCI MCP Server page