CircleCI MCP Server Cursor IDE Setup 2026

How do you set up the CircleCI MCP server in Cursor? Generate a CircleCI Personal API Token, add a circleci-mcp-server block to mcp.json with that token via npx, restart Cursor, and ask it something like "why did my last build fail?" instead of clicking through the CircleCI dashboard yourself. The server auto-detects your project from your Git remote and current branch, so most prompts don't need you to specify a project name.

One thing worth knowing before you set this up: CircleCI has been migrating MCP access toward its CLI (circleci mcp cursor enable) and a hosted server, and the standalone @circleci/mcp-server-circleci npm package is now in maintenance mode — it still works and is what CircleCI's own setup docs currently show for manual Cursor configuration, but if you're setting this up fresh, check CircleCI's docs for whether the CLI-based path has become the default by the time you read this.

What the CircleCI MCP Server Enables

Once connected, Cursor can:

Prerequisites

Step 1: Generate a CircleCI Personal API Token

1. Log into CircleCI and go to User Settings → Personal API Tokens
2. Click to create a new token
3. Give it a name you'll recognize later, like cursor-mcp-2026
4. Copy the token — treat it like any other credential, since it inherits your account's access to every project you can see

Step 2: Add the Server to mcp.json

In Cursor, open Customize → MCPs and add a new MCP server, or edit mcp.json directly:

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

CIRCLECI_BASE_URL defaults to https://circleci.com — only change it if your org runs CircleCI Server (self-hosted). For production or team rollouts, consider pinning a specific version of the package instead of @latest, so a future release doesn't silently change behavior mid-project.

Step 3: Restart and Verify

Restart Cursor, return to the MCPs list, and confirm circleci-mcp-server shows up as connected. In chat, try:

List my followed projects on CircleCI

Or, from inside a repo with a recent build:

Why did my last build fail?

The integration reads your current Git remote and branch automatically, so this works without naming the project explicitly as long as you're running it from inside the actual repo.

Practical Workflows

Debugging a red build without leaving the editor

My last pipeline failed on the "test" job. Pull the failure logs and tell me what actually broke — is it a real test failure or a flaky test?

Pre-push config validation

Validate my .circleci/config.yml before I push this branch — I just added a new deploy job and want to catch syntax errors now

Flaky test triage

Find flaky tests in this project from the last 20 pipeline runs and rank them by how often they fail

Triggering a pipeline from chat

Run the pipeline for my current branch and let me know when it starts

Troubleshooting

"Unauthorized" errors despite a token that looks correct
Regenerate the token and retype it directly into mcp.json rather than copy-pasting — a trailing space or newline from clipboard is a common, silent cause, since the JSON stays valid either way but CircleCI rejects the malformed string.

Cursor can't find "my project" automatically
The auto-detection relies on your current working directory having a Git remote that matches a project CircleCI already knows about (i.e., one you've followed). If you're working from a fork or a repo CircleCI hasn't indexed, name the project and org explicitly in your prompt instead.

"Why did my build fail" gives a vague or generic answer
Ask it to pull the actual job log for the specific failing step rather than the whole pipeline — a scoped request ("pull the log for the 'integration-tests' job") tends to get a more precise diagnosis than "what happened."

Package feels unmaintained / you've read it's deprecated
That's accurate as of this writing — the standalone npm package is in maintenance mode, with CircleCI steering new setups toward the CLI-based circleci mcp command or a hosted server. The npx config above still works and is what CircleCI's own docs currently show for Cursor, but don't be surprised if a future guide replaces it with a CLI-first flow.

When This Doesn't Make Sense

If your org runs CircleCI Server behind a VPN with no direct network path from your development machine, the remote token-based connection in this guide won't reach it without additional network configuration — check with your DevOps team about whether CIRCLECI_BASE_URL needs to point at an internal endpoint and whether that endpoint is reachable at all from where Cursor runs.

Frequently Asked Questions

Q: Is the npm package still the right way to set this up, or should I use the CLI instead?
A: As of this writing, CircleCI's own Cursor setup documentation shows the npx @circleci/mcp-server-circleci config in this guide. The package itself is in maintenance mode, and CircleCI is steering new integrations toward a CLI-based command (circleci mcp) or hosted server — both work, but check CircleCI's current docs if you want the more actively maintained path.

Q: What permissions does the CircleCI Personal API Token carry?
A: Whatever your CircleCI account can already access — all projects you're a member of or have followed. There's no separate scoping step for the token beyond your account's own project access.

Q: Can Cursor trigger a deploy, or only read pipeline status?
A: It can trigger pipelines, including ones that deploy, if your .circleci/config.yml is set up that way and your account has permission to run them. Be deliberate about letting an AI-driven prompt trigger a pipeline connected to a production deploy — treat "run the pipeline" the same way you'd treat any other automated trigger you didn't manually review first.

Q: Does the server work with CircleCI Server (self-hosted), not just circleci.com?
A: Point CIRCLECI_BASE_URL at your self-hosted instance instead of the default https://circleci.com. Confirm your token was generated against that same instance — tokens aren't portable between CircleCI Server and the cloud product.

Q: How does "find flaky tests" actually work — is it a guess or based on real data?
A: It's based on real pass/fail history across recent pipeline runs for your project's test suite, not a heuristic guess from a single run. A test that's failed inconsistently across multiple runs on the same code gets flagged; a test that failed once due to an actual code change won't show up as flaky.

Related Guides

---