CircleCI MCP Server

Add to your client

Copy the config for your MCP client and paste it into its config file.

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

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

About CircleCI MCP Server

Tools & capabilities (12)

When to use it

• Use it when a build fails and you want the failure logs pulled and explained right in your editor.
• Use it when you need to validate or fix a .circleci/config.yml before pushing.
• Use it when chasing flaky tests that intermittently break CI.
• Use it when you want to trigger, re-run, or roll back a pipeline by asking in natural language.
• Use it when auditing CircleCI spend and right-sizing resource classes.
• Use it when building and evaluating prompt templates as part of a CircleCI pipeline.

Quick setup

1. 1Generate a CircleCI Personal API Token at app.circleci.com/settings/user/tokens.
2. 2Add the server to your MCP client config with command npx -y @circleci/mcp-server-circleci (or the Docker image).
3. 3Set the CIRCLECI_TOKEN environment variable (and CIRCLECI_BASE_URL if self-hosted/server).
4. 4Restart your MCP client so it loads the server.
5. 5Verify by asking the assistant to list your followed projects or the latest pipeline status.

CircleCI MCP Server FAQ