How to add CircleCI MCP Server to Cursor

Official CircleCI MCP server: inspect and fix failed builds, query pipelines in natural language. Paste the config into ~/.cursor/mcp.json and restart Cursor.

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

Cursor 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 Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
2Paste the CircleCI MCP Server config below into the "mcpServers" object.
3Fill in placeholder secrets, then save.
4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
5Ask Cursor to use one of CircleCI MCP Server's tools to confirm it's connected.

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 Cursor

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 + Cursor FAQ

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the CircleCI MCP Server config there under the "mcpServers" key and restart the client.

Is CircleCI MCP Server safe to use with Cursor?

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