Labsco
CircleCI-Public logo

CircleCI

★ 84

from CircleCI-Public

Enable AI Agents to fix build failures from CircleCI.

🔥🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#email#automation#cloud#devops#git#maps#security

CircleCI MCP Server

Model Context Protocol (MCP) is a new, standardized protocol for managing context between large language models (LLMs) and external systems. In this repository, we provide an MCP Server for CircleCI.

Use Cursor, Windsurf, Copilot, Claude, or any MCP-compatible client to interact with CircleCI using natural language — without leaving your IDE.

Tools

ToolDescription
analyze_diffAnalyze git diffs against cursor rules for violations
config_helperValidate and get guidance for your CircleCI configuration
create_prompt_templateGenerate structured prompt templates for AI applications
download_usage_api_dataDownload usage data from the CircleCI Usage API
find_flaky_testsIdentify flaky tests by analyzing test execution history
find_underused_resource_classesFind jobs with underused compute resources
get_build_failure_logsRetrieve detailed failure logs from CircleCI builds
get_job_test_resultsRetrieve test metadata and results for CircleCI jobs
get_latest_pipeline_statusGet the status of the latest pipeline for a branch
list_artifactsList artifacts produced by a CircleCI job
list_component_versionsList all versions for a CircleCI component
list_followed_projectsList all CircleCI projects you're following
recommend_prompt_template_testsGenerate test cases for prompt templates
rerun_workflowRerun a workflow from start or from the failed job
run_evaluation_testsRun evaluation tests on a CircleCI pipeline
run_pipelineTrigger a pipeline to run
run_rollback_pipelineTrigger a rollback for a project

Self-Managed Remote MCP Server

Run the MCP server centrally (for example on Kubernetes or Docker) so your team shares one deployment. Choose how developers authenticate:

Choose a deployment mode

ModeWhen to useServer setupClient setupCircleCI audit trail
Per-user tokens (recommended)Teams with SSO-backed Personal API TokensREQUIRE_REQUEST_TOKEN=true, no server PATEach dev forwards their PATPer developer
Shared token (interim)Quick rollout, single service identity OKCIRCLECI_TOKEN on server, REQUIRE_REQUEST_TOKEN=false (explicit opt-out)No auth header neededSingle shared identity

Security: Request authentication is on by default in remote mode. The shared-token mode disables it (REQUIRE_REQUEST_TOKEN=false), making every caller able to act as the server's CIRCLECI_TOKEN identity with no credentials. Only enable it on a network you fully trust, and prefer per-user tokens otherwise. Terminating TLS at an ingress provides encryption, not authentication.

1. Deploy the server

Both modes use remote HTTP mode (start=remote). Publish port 8000 (or your chosen port).

Per-user tokens (recommended) — accessed via mcp-remote from localhost:

docker run --rm -p 8000:8000 \
  -e start=remote \
  -e port=8000 \
  -e REQUIRE_REQUEST_TOKEN=true \
  circleci/mcp-server-circleci

Per-user tokens (recommended) — accessed via mcp-remote from a public hostname:

docker run --rm -p 8000:8000 \
  -e start=remote \
  -e port=8000 \
  -e REQUIRE_REQUEST_TOKEN=true \
  -e MCP_ALLOWED_HOSTS=my-mcp.example.com \
  circleci/mcp-server-circleci

Shared token (interim) — accessed via mcp-remote from a public hostname:

docker run --rm -p 8000:8000 \
  -e start=remote \
  -e port=8000 \
  -e CIRCLECI_TOKEN=your-shared-circleci-pat \
  -e REQUIRE_REQUEST_TOKEN=false \
  -e MCP_ALLOWED_HOSTS=my-mcp.example.com \
  circleci/mcp-server-circleci

Environment variables:

VariableDescription
start=remoteStarts the HTTP+SSE MCP server instead of stdio
portListening port inside the container (default: 8000)
REQUIRE_REQUEST_TOKENReject requests without Authorization: Bearer or Circle-Token header. Defaults to required; set REQUIRE_REQUEST_TOKEN=false to allow unauthenticated requests (shared-token mode)
CIRCLECI_TOKENShared fallback PAT for all requests when per-user headers are not sent
CIRCLECI_BASE_URLOptional — required for on-prem only (default: https://circleci.com)
DISABLE_TELEMETRY=trueOpt out of usage metrics export
MCP_ALLOWED_HOSTSComma-separated list of additional Host header values to allow (e.g. my-mcp.example.com,my-mcp.example.com:443). Loopback hostnames are always allowed. Required for any non-loopback deployment.
MCP_ALLOWED_ORIGINSComma-separated list of additional Origin header values to allow (e.g. https://my-app.example.com). Loopback origins are always allowed. Only needed when a browser directly reaches this server (not via mcp-remote).
MCP_BIND_HOSTNetwork interface to bind to (default: 0.0.0.0). Set to 127.0.0.1 to restrict to loopback only (not compatible with Docker -p port mapping).

DNS-rebinding protection: The remote transport validates the Host header on every /mcp request. By default only loopback addresses (localhost, 127.0.0.1, [::1]) are accepted. Public deployments must set MCP_ALLOWED_HOSTS to the hostname clients use, or all /mcp requests will receive 403 Forbidden. The /ping health-check endpoint is not guarded so load-balancer probes continue to work regardless of Host.

The Origin header (sent by browsers) is also validated when present. Non-browser clients such as mcp-remote never send Origin, so they are unaffected by this check.

Behind a reverse proxy: If your proxy rewrites Host to the backend address (nginx's default), add proxy_set_header Host $host; to pass the original hostname through, then set MCP_ALLOWED_HOSTS to that public hostname. Alternatively, set MCP_ALLOWED_HOSTS to whatever hostname the proxy does forward.

The server accepts per-request tokens via:

  • Authorization: Bearer <circleci-pat>
  • Circle-Token: <circleci-pat>

If a client sends a header token, it takes precedence over CIRCLECI_TOKEN on the server.

Telemetry metrics recorded during a request are exported using the same token as that request.

2. Configure clients

Most MCP clients only support local (stdio) processes. Use mcp-remote, a third-party stdio-to-HTTP bridge, to connect them to your remote server.

URL scheme: Use http://localhost:8000/mcp with --allow-http for local testing. In production, terminate TLS at your ingress/load balancer and use https://your-host/mcp without --allow-http.

Windows: Avoid spaces around the colon in --header values. Put the full Bearer <token> value in an environment variable.

Security: Examples use npx for convenience. For production or team rollouts, pin a specific version in your MCP config (for example mcp-remote@0.1.38 instead of mcp-remote). Do not use versions below 0.1.16 (CVE-2025-6514).

Client configuration: per-user tokens

Each developer forwards their own CircleCI Personal API Token on every request:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "mcpServers": {
    "circleci-mcp-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--allow-http",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ${input:circleci-token}"
      }
    }
  }
}

Replace http://localhost:8000/mcp with your team's server URL. Cursor and VS Code support ${input:...} prompts; other clients can set AUTH_HEADER directly.

Client configuration: shared token

When the server has CIRCLECI_TOKEN set and is started with REQUIRE_REQUEST_TOKEN=false (request auth is on by default and must be explicitly disabled), clients do not need to send a token:

{
  "mcpServers": {
    "circleci-mcp-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--allow-http"
      ]
    }
  }
}

Claude Desktop and CLI clients

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

#!/bin/bash
export AUTH_HEADER="Bearer your-circleci-token"
npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}"

Make it executable (chmod +x circleci-remote-mcp.sh), then reference it from your MCP config:

{
  "mcpServers": {
    "circleci-remote-mcp-server": {
      "command": "/full/path/to/circleci-remote-mcp.sh"
    }
  }
}

Claude Code

claude mcp add circleci-mcp-server \
  -e AUTH_HEADER="Bearer your-circleci-token" \
  -- npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}"

Omit --header and AUTH_HEADER when using a shared-token server.

3. Verify the deployment

# Health check (no auth required)
curl http://localhost:8000/ping

# Should return 401 when REQUIRE_REQUEST_TOKEN=true and no token is sent
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Should return 200 with a valid Bearer token and MCP Accept headers
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-circleci-pat" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Demo

Watch it in action

Example: "Find the latest failed pipeline on my branch and get logs" — see the wiki for more examples.

https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74

Tool Details

analyze_diff

Analyzes git diffs against cursor rules to identify rule violations.

Provide:

  • Git diff content (e.g. git diff --cached, git diff HEAD)
  • Repository rules from .cursorrules or .cursor/rules

Returns detailed violation reports with confidence scores and explanations.

Useful for:

  • Pre-commit code quality checks
  • Ensuring consistency with team coding standards
  • Catching rule violations before code review
config_helper

Assists with CircleCI configuration tasks by providing guidance and validation.

  • Validates your .circleci/config.yml for syntax and semantic errors
  • Provides detailed validation results and configuration recommendations
  • Example: "Validate my CircleCI config"
create_prompt_template

Generates structured prompt templates for AI-enabled applications based on feature requirements.

  • Transforms user requirements into optimized prompt templates
  • Returns a structured template and a context schema defining required input parameters
  • Example: "Create a prompt template for generating bedtime stories by age and topic"
download_usage_api_data

Downloads usage data from the CircleCI Usage API for a given organization. Accepts flexible date input (e.g., "March 2025" or "last month"). Cloud-only feature.

Option 1: Start a new export job by providing:

  • orgId, startDate, endDate (max 32 days), outputDir

Option 2: Check/download an existing export job by providing:

  • orgId, jobId, outputDir

Returns a CSV file with CircleCI usage data for the specified time frame.

[!NOTE] Usage data can be fed into the find_underused_resource_classes tool for cost optimization analysis.

find_flaky_tests

Identifies flaky tests in your CircleCI project by analyzing test execution history. Leverages the flaky test detection feature in CircleCI.

This tool can be used in three ways:

  1. Using Project Slug (Recommended):

    • First use list_followed_projects to get your projects, then:
    • Example: "Get flaky tests for my-project"

  2. Using CircleCI Project URL:

  3. Using Local Project Context:

    • Works from your local workspace by providing workspace root and git remote URL
    • Example: "Find flaky tests in my current project"

Output modes:

  • Text (default): Returns flaky test details in text format
  • File (requires FILE_OUTPUT_DIRECTORY env var): Creates a directory with flaky test details
find_underused_resource_classes

Analyzes a CircleCI usage data CSV file to find jobs with average or max CPU/RAM usage below a given threshold (default: 40%).

Provide a CSV file obtained from download_usage_api_data.

Returns a markdown list of underused jobs organized by project and workflow — useful for identifying cost optimization opportunities.

get_build_failure_logs

Retrieves detailed failure logs from CircleCI builds. This tool can be used in three ways:

  1. Using Project Slug and Branch (Recommended):

    • First use list_followed_projects to get your projects, then:
    • Example: "Get build failures for my-project on the main branch"

  2. Using CircleCI URLs:

  3. Using Local Project Context:

    • Works from your local workspace by providing workspace root, git remote URL, and branch name
    • Example: "Find the latest failed pipeline on my current branch"

The tool returns formatted logs including:

  • Job names
  • Step-by-step execution details
  • Failure messages and context
get_job_test_results

Retrieves test metadata for CircleCI jobs, allowing you to analyze test results without leaving your IDE. This tool can be used in three ways:

  1. Using Project Slug and Branch (Recommended):

    • Example: "Get test results for my-project on the main branch"

  2. Using CircleCI URL:

    • Job URL: https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789
    • Workflow URL: https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def
    • Pipeline URL: https://app.circleci.com/pipelines/github/org/repo/123

  3. Using Local Project Context:

    • Works from your local workspace by providing workspace root, git remote URL, and branch name

The tool returns:

  • Summary of all tests (total, successful, failed)
  • Detailed info on failed tests: name, class, file, error message, duration
  • List of successful tests with timing
  • Filter by test result

[!NOTE] Test metadata must be configured in your CircleCI config. See Collect Test Data for setup instructions.

get_latest_pipeline_status

Retrieves the status of the latest pipeline for a given branch. This tool can be used in three ways:

  1. Using Project Slug and Branch (Recommended):

    • Example: "Get the status of the latest pipeline for my-project on the main branch"

  2. Using CircleCI Project URL:

  3. Using Local Project Context:

    • Works from your local workspace by providing workspace root, git remote URL, and branch name

Example output:

---
Workflow: build
Status: success
Duration: 5 minutes
Created: 4/20/2025, 10:15:30 AM
Stopped: 4/20/2025, 10:20:45 AM
---
Workflow: test
Status: running
Duration: unknown
Created: 4/20/2025, 10:21:00 AM
Stopped: in progress
list_artifacts

Retrieves the list of artifacts produced by a CircleCI job. This tool can be used in three ways:

  1. Using Project Slug and Branch (Recommended):

    • First use list_followed_projects to get your projects, then:
    • Example: "List artifacts for my-project on the main branch"

  2. Using CircleCI URL:

    • Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
    • Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
    • Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123

  3. Using Local Project Context:

    • Works from your local workspace by providing workspace root, git remote URL, and branch name

Useful for:

  • Finding download URLs for build artifacts (binaries, reports, logs)
  • Checking what artifacts were produced by a pipeline run
list_component_versions

Lists all versions for a specific CircleCI component in an environment. Includes deployment status, commit information, and timestamps.

The tool will prompt you to select the component and environment if not provided.

Useful for:

  • Identifying which version is currently live
  • Selecting target versions for rollback operations
  • Getting deployment details (pipeline, workflow, job)
list_followed_projects

Lists all projects that the user is following on CircleCI.

  • Shows all projects you have access to with their projectSlug
  • Example: "List my CircleCI projects"

Example output:

Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)

[!NOTE] The projectSlug (not the project name) is required for many other CircleCI tools.

recommend_prompt_template_tests

Generates test cases for prompt templates to ensure they produce expected results.

  • Creates diverse test scenarios based on your prompt template and context schema
  • Returns an array of recommended test cases with various parameter combinations
  • Example: "Generate tests for my bedtime story prompt template"
rerun_workflow

Reruns a workflow from its start or from the failed job.

Returns the ID of the newly-created workflow and a link to monitor it.

run_evaluation_tests

Runs evaluation tests (also known as "Prompt Tests") on a CircleCI pipeline. Generates an appropriate CircleCI configuration and triggers a pipeline using it.

This tool can be used in three ways:

  1. Using Project Slug and Branch (Recommended):

    • First use list_followed_projects to get your projects, then:
    • Example: "Run evaluation tests for my-project on the main branch"

  2. Using CircleCI URL:

  3. Using Local Project Context:

    • Works from your local workspace by providing workspace root, git remote URL, and branch name

The tool accepts prompt template files and returns a URL to monitor the triggered pipeline.

[!NOTE] If the project has multiple pipeline definitions, the tool will return a list of available pipelines for you to choose from.

run_pipeline

Triggers a pipeline to run. This tool can be used in three ways:

  1. Using Project Slug and Branch (Recommended):

    • Example: "Run the pipeline for my-project on the main branch"

  2. Using CircleCI URL:

  3. Using Local Project Context:

    • Works from your local workspace by providing workspace root, git remote URL, and branch name

The tool returns a link to monitor the pipeline execution.

run_rollback_pipeline

Triggers a rollback for a CircleCI project. The tool interactively guides you through:

  1. Project Selection — lists followed projects for you to choose from
  2. Environment Selection — lists available environments (auto-selects if only one)
  3. Component Selection — lists available components (auto-selects if only one)
  4. Version Selection — displays available versions; you select the target for rollback
  5. Rollback Mode Detection — checks if a rollback pipeline is configured
  6. Execute Rollback — two options:
    • Pipeline Rollback: triggers the rollback pipeline
    • Workflow Rerun: reruns a previous workflow using its workflow ID
  7. Confirmation — summarizes and confirms before execution

Telemetry

The server supports OpenTelemetry metrics for tracking tool usage. Metrics are exported unless you set DISABLE_TELEMETRY=true. On remote deployments, metrics use the same token as the request (per-user PAT or shared server PAT).

MetricDescription
circleci.mcp.tool.invocationsTool invocation count
circleci.mcp.tool.duration_msExecution time in ms
circleci.mcp.tool.errorsError count

Development

Building Docker Container

You can build the Docker container locally using:

docker build -t circleci:mcp-server-circleci .

This will create a Docker image tagged as circleci:mcp-server-circleci that you can use with any MCP client.

Local stdio mode (single developer, token on the client):

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

Remote mode (centralized server for a team): see Self-Managed Remote MCP Server.

Development with MCP Inspector

The easiest way to iterate on the MCP Server is using the MCP inspector. You can learn more about the MCP inspector at https://modelcontextprotocol.io/docs/tools/inspector

  1. Start the development server:

    pnpm watch # Keep this running in one terminal

  2. In a separate terminal, launch the inspector:

    pnpm inspector

  3. Configure the environment:

    • Add your CIRCLECI_TOKEN to the Environment Variables section in the inspector UI
    • The token needs read access to your CircleCI projects
    • Optionally set your CircleCI Base URL (defaults to https://circleci.com)

Testing

  • Run the test suite:

    pnpm test

  • Run tests in watch mode during development:

    pnpm test:watch

For more detailed contribution guidelines, see CONTRIBUTING.md