CircleCI MCP server

CI/CD context for AI tools

The CircleCI MCP server makes your build system understandable by AI tools like Cursor, Claude Code, Windsurf, and more. It’s built on the Model Context Protocol (MCP), a lightweight standard that allows LLM-powered agents to fetch structured data from external systems.

By connecting to the CircleCI MCP Server, agents gain real-time visibility into:

Build logs and test outputs
Pipeline statuses
Recent configuration changes
Workflow performance metrics

That means instead of digging through job logs or dashboard UIs, you can ask:

why did my last build fail?

and get all the context you need to fix the issue and keep moving without breaking stride.

Turn build data into action

Once installed, the MCP server makes your CI/CD data accessible through natural language. LLM-based tools can:

Diagnose failing builds
Get structured error summaries and logs.

Trace failures to recent changes
Connect regressions to commits, diffs, or workflows.

Spot flaky tests
Surface instability patterns from test history.

Recommend improvements
Suggest config or timing optimizations in context.

Bring CI data into your editor
Use LLM tools to reason through builds without switching tabs.

With access to both code and build context, these tools can help you fix bugs faster, ship changes with confidence, and stay focused on the work that matters.

Recommended setup

For local editors — use the CircleCI CLI. The MCP server is built directly into the CLI, which is the recommended way to connect Cursor, VS Code, Claude Desktop, and similar tools to CircleCI.

For web-hosted agents like Claude.ai, or if company policy prefers — use the hosted MCP server, which connects via OAuth2 and requires no local install.

Both can be active at the same time.

Note for current standalone MCP server users: Our original standalone MCP server is in maintenance mode and is no longer recommended. If you need to stay on the standalone server for now, use version 0.19.0 or later. Installs that use the @latest tag pick this up automatically; if you pin a specific version, point your configuration at @circleci/mcp-server-circleci@0.19.0.

Get started with MCP

Prerequisites

Hosted CircleCI MCP server:

An AI coding assistant / MCP host that supports remote MCP servers over streamable HTTP.
If your MCP host cannot complete an OAuth2 flow, a CircleCI personal API token (see Managing API Tokens.

CircleCI CLI MCP:

Install the CircleCI CLI, then run circleci auth login or set the CIRCLE_TOKEN environment variable.

Configuration instructions

Heads up: The old local MCP server installed with npx or Docker and a CIRCLECI_TOKEN is deprecated. If your AI assistant still has it configured, remove it before setting up the options below. For example, in Claude Code run claude mcp remove circleci-mcp-server.

Option 1 — Hosted MCP server

CircleCI hosts a remote MCP server at https://mcp.circleci.com/v1/mcp. Nothing to install. Authenticate with OAuth2 by signing in with your CircleCI account. If your MCP host cannot complete an OAuth2 flow (for example, headless or automated setups), see the fall back below.

Claude Code

Authenticate with OAuth2 (recommended):

Add the server:

claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp

Run /mcp inside Claude Code and select circleci-mcp-server.
Select Authenticate to complete the OAuth2 sign-in in your browser.

Authenticate with a personal API token (fallback):

claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp \
  --header "Authorization: Bearer <your-circleci-token>"

Claude Code MCP docs

Claude Desktop & claude.ai

Authenticate with OAuth2 (recommended):

Go to Settings > Connectors.
Select Add custom connector.
Enter https://mcp.circleci.com/v1/mcp as the server URL.
Select Add, then complete the OAuth2 sign-in in your browser.

Custom connectors docs

Cursor

Authenticate with OAuth2 (recommended):

Use this link to add the server automatically: Add CircleCI MCP server to Cursor. This opens an install prompt in your Cursor settings.
Select Install. The server shows a "Needs authentication" label with a Connect button.
Select Connect to start the OAuth2 flow in your browser.

Or add this to your Cursor mcp.json file:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "url": "https://mcp.circleci.com/v1/mcp"
    }
  }
}

Authenticate with a personal API token (fallback):

{
  "mcpServers": {
    "circleci-mcp-server": {
      "url": "https://mcp.circleci.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-circleci-token>"
      }
    }
  }
}

Cursor setup docs

VS Code

Authenticate with OAuth2 (recommended):

Use this link to add the server automatically: Add CircleCI MCP server to VS Code.

Or add this to your .vscode/mcp.json file:

{
  "servers": {
    "circleci-mcp-server": {
      "type": "http",
      "url": "https://mcp.circleci.com/v1/mcp"
    }
  }
}

Authenticate with a personal API token (fallback):

{
  "servers": {
    "circleci-mcp-server": {
      "type": "http",
      "url": "https://mcp.circleci.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-circleci-token>"
      }
    }
  }
}

VS Code setup docs

Windsurf

Authenticate with OAuth2 (recommended):

Add this to your Windsurf mcp_config.json file:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "serverUrl": "https://mcp.circleci.com/v1/mcp"
    }
  }
}

Authenticate with a personal API token (fallback):

{
  "mcpServers": {
    "circleci-mcp-server": {
      "serverUrl": "https://mcp.circleci.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-circleci-token>"
      }
    }
  }
}

Windsurf setup docs

Need a personal API token? See Managing API tokens. Treat the token like a password — reference it through an environment variable or secret store where your MCP host supports it. Full instructions: Connecting to the CircleCI MCP server.

Option 2 — CircleCI CLI MCP (local)

The CircleCI CLI includes a built-in MCP server that runs locally on your machine using your existing CLI authentication. Use this if you prefer a fully local setup.

CircleCI CLI MCP

Prerequisites:

The CircleCI CLI installed.
An authenticated CLI session. Run circleci auth login, or set the CIRCLE_TOKEN environment variable.

Enable the MCP server for your AI assistant with one command:

circleci mcp claude enable    # Claude Desktop
circleci mcp cursor enable    # Cursor
circleci mcp vscode enable    # VS Code

To disable it, replace enable with disable.

Start the server manually over the default stdio transport, or stream it over HTTP:

circleci mcp start     # start over stdio
circleci mcp stream    # stream over HTTP

CLI MCP setup docs · CLI MCP command reference

Available tools

Each MCP exposes a different set of tools. The hosted server provides a curated set of CI/CD actions tuned for AI-driven development and agentic workflows, while the CLI MCP exposes the full CircleCI CLI. Whichever you connect, the tools give AI developers structured CI/CD context for faster, more reliable release cycles.

Hosted MCP server tools

Tool	Uses
`analyze_diff`	Catch rule violations in your diff before code review
`config_helper`	Fix config issues before they break your pipeline
`create_prompt_template`	Generate prompts that support consistent AI behavior
`download_usage_api_data`	Export CircleCI usage data for cost and capacity analysis
`find_flaky_tests`	Identify and troubleshoot unstable tests
`find_underused_resource_classes`	Find jobs with low CPU/RAM utilization for downsizing
`get_build_failure_logs`	Debug and resolve failed builds faster
`get_job_test_results`	Understand and fix test failures and performance issues
`get_latest_pipeline_status`	Monitor and act on pipeline health
`list_artifacts`	Find and download artifacts produced by a job
`list_component_versions`	View deployed versions and pick rollback targets
`list_followed_projects`	Find projects you follow and their `projectSlug`
`recommend_prompt_template_tests`	Test and improve prompt reliability
`rerun_workflow`	Rerun workflows from the beginning or from a failed job
`run_evaluation_tests`	Run prompt evaluation tests on a CircleCI pipeline
`run_pipeline`	Trigger builds while staying in your editor
`run_rollback_pipeline`	Roll back faulty deployments with a single command

CLI MCP tools

The CLI MCP exposes the entire CircleCI CLI as tools, including:

Config authoring — validate, process, pack, and generate config YAML.
Org and project management — contexts, env vars, project/org settings.
Orb tooling — create, publish, validate, and diff orb versions.
Security policy — push, test, and evaluate Rego policies.
Self-hosted runners — manage runner resource classes and tokens.
iOS code signing — manage certificates and signing configs.
Deploy tracking — list and instrument deploys.
Docker Layer Cache — purge DLC.
Direct API access — call the CircleCI API directly via circleci api.

Learn more

Go deeper on the CircleCI MCP with docs, background reading, and the latest platform updates:

CircleCI MCP overview – Supported tools, best practices, and how the hosted and CLI MCPs compare.
Connect to the hosted MCP server – The hosted remote server, no install required.
Connect to the CircleCI CLI MCP – The local MCP built into the CircleCI CLI.
Blog post: What is a remote MCP server? – Background on remote MCP and why it matters.
Blog post: Rebuilding the CircleCI CLI from scratch – The story behind the rebuilt CLI that powers the CLI MCP.
CircleCI changelog – See the latest platform updates and feature releases.

Overview

Features

Integrations

Role

Use case

Company size

Developers

Explore

Community

Benefits

Compare

Company

Overview

Features

Integrations

Role

Use case

Company size

Developers

Explore

Community

Benefits

Compare

Company

Explore

CircleCI MCP Server

CI/CD context for AI tools

Turn build data into action

Recommended setup

Get started with MCP

Prerequisites

Configuration instructions

Option 1 — Hosted MCP server

Option 2 — CircleCI CLI MCP (local)

Available tools

Hosted MCP server tools

CLI MCP tools

Learn more