Skip to content
CircleCI

CircleCI MCP Server

Connect your AI assistant to your CircleCI data to debug failures, analyze test results, and improve pipelines using natural language.

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.

Get started with MCP

The CircleCI MCP Server runs locally and integrates with a variety of editors and LLM development tools.

Below are ready-to-use configuration examples to help you install the MCP server in your preferred environment.

Prerequisites

Before setting up your IDE, make sure you have the following:

Configuration instructions

Cursor

Using NPX:


{
  "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"
      }
    }
  }
}

Using Docker:


{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CIRCLECI_TOKEN",
        "-e", "CIRCLECI_BASE_URL",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com"
      }
    }
  }
}

Cursor setup docs

VS Code

Using NPX:


{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

Using Docker:


{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CIRCLECI_TOKEN",
        "-e", "CIRCLECI_BASE_URL",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

VS Code setup docs

Claude Desktop

Using NPX:


{
  "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"
      }
    }
  }
}

Using Docker:


{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CIRCLECI_TOKEN",
        "-e", "CIRCLECI_BASE_URL",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com"
      }
    }
  }
}

Config file location:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop setup docs

Claude Code

Using NPX:


claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest

Using Docker:


claude mcp add circleci-mcp-server \
  -e CIRCLECI_TOKEN=your-circleci-token \
  -e CIRCLECI_BASE_URL=https://circleci.com \
  -- docker run --rm -i \
  -e CIRCLECI_TOKEN \
  -e CIRCLECI_BASE_URL \
  circleci:mcp-server-circleci

Claude Code setup docs

Windsurf

Using NPX:


{
  "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"
      }
    }
  }
}

Using Docker:


{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CIRCLECI_TOKEN",
        "-e", "CIRCLECI_BASE_URL",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com"
      }
    }
  }
}

Windsurf setup docs

Amazon Q Developer

Configuration files:
Amazon Q Developer stores MCP client configuration in JSON format in mcp.json files.

- Global configuration: ~/.aws/amazonq/mcp.json (applies to all workspaces)
- Workspace configuration: .amazonq/mcp.json (specific to the current project)

Both are optional; if both exist, Amazon Q merges them. If a server is defined in both, the workspace config overrides and a warning is shown.

Using NPX (local MCP server):

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // optional, required for on-prem only
      },
      "timeout": 60000
    }
  }
}

Using a Self-Managed Remote MCP Server:

Create a wrapper script (e.g. circleci-remote-mcp.sh):

#!/bin/bash
export CIRCLECI_TOKEN="your-circleci-token"
npx mcp-remote http://your-circleci-remote-mcp-server-endpoint:8000/mcp --allow-http

Make it executable:

chmod +x circleci-remote-mcp.sh

Then add it to Amazon Q Developer:

q mcp add --name circleci --command "/full/path/to/circleci-remote-mcp.sh"

IDE Integration:
You can also add servers through the Amazon Q MCP configuration UI:

  • Choose global or workspace scope (~/.aws/amazonq/mcp.json vs .amazonq/mcp.json)
  • Enter a server name (e.g. circleci-remote-mcp)
  • Set transport protocol: stdio
  • Set command: the wrapper script path (e.g. /full/path/to/circleci-remote-mcp.sh)
  • Save configuration

Install with Smithery 

npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci@latest --client claude

Available tools

From accelerating AI-driven development to orchestrating agentic workflows, each tool exposed by the MCP server equips AI developers with structured CI/CD context for faster, more reliable release cycles.

Tool Uses
config_helper Fix config issues before they break your pipeline
create_prompt_template Generate prompts that support consistent AI behavior
find_flaky_tests Identify and troubleshoot unstable tests
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_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_pipeline Trigger builds while staying in your editor
run_rollback_pipeline Roll back faulty deployments with a single command

Learn more

Get started with the CircleCI MCP Server, dive into examples, or keep up with platform updates: