Overview

The CircleCI MCP Server implements the Model Context Protocol (MCP) to connect CircleCI infrastructure with MCP‑aware AI clients and tooling. It exposes a collection of server-side “tools” that let language models and developer assistants (Cursor, Windsurf, Copilot, Claude, etc.) query and act on CircleCI projects using natural language — without switching context out of the editor.

By bridging CircleCI’s APIs and the MCP specification, the server enables contextual tasks such as inspecting pipeline and job results, downloading logs and artifacts, identifying flaky tests or underutilized resource classes, validating config, and triggering pipelines or reruns. This is useful for developers, SREs, and platform engineers who want AI-driven workflows that operate directly on CI/CD state.

Repository and releases: https://github.com/CircleCI-Public/mcp-server-circleci

Features

Integrates CircleCI APIs with MCP-compatible clients over stdio or HTTP
Secure use of CircleCI Personal API tokens (environment- or prompt-based)
Tools for diagnostics (logs, test results, failure traces)
Automation: trigger pipelines, rerun workflows, run rollback pipelines
Analysis helpers: diff checks, flaky test detection, underused resources
Prompt template generation and evaluation/testing helpers
Config validation and guidance for circleci/config.yml
Optional Docker image for local / containerized deployment

Installation / Configuration

Prerequisites:

CircleCI Personal API token
Node.js >= 18 (if using NPX) and pnpm for development workflows
Docker (optional, for containerized runs)

NPX (run locally via MCP client like Cursor)

{
  "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",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Docker (run the server in a container)

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

Self‑managed remote MCP endpoint (client connects to remote server URL)

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "servers": {
    "circleci-mcp-server-remote": {
      "url": "http://your-remote-mcp-server:8000/mcp"
    }
  }
}

Notes:

CIRCLECI_BASE_URL is optional; set it for self-hosted/on‑prem CircleCI instances.
MAX_MCP_OUTPUT_LENGTH controls the maximum MCP response length (default ~50k).

Available Tools / Resources

The MCP server exposes a number of tools (each callable from an MCP client). Key tools include:

Tool	What it does
analyze_diff	Scan git diffs for policy or style violations against configured rules
config_helper	Validate and provide guidance for circleci/config.yml
create_prompt_template	Generate structured prompt templates for AI-driven tasks
download_usage_api_data	Fetch usage and billing data from the CircleCI Usage API
find_flaky_tests	Detect flaky tests using historical execution data
find_underused_resource_classes	Identify jobs using oversized compute where resources are underutilized
get_build_failure_logs	Retrieve detailed failure logs for a specific build
get_job_test_results	Fetch test metadata and results for jobs
get_latest_pipeline_status	Query the latest pipeline status for a branch
list_artifacts	List artifacts produced by a job
list_component_versions	Enumerate component versions for a project
list_followed_projects	List CircleCI projects followed by the user
recommend_prompt_template_tests	Suggest test cases for prompt templates
rerun_workflow	Rerun a workflow (from start or from failed job)
run_evaluation_tests	Run evaluation tests against a pipeline
run_pipeline	Trigger a new pipeline
run_rollback_pipeline	Trigger a rollback pipeline for a project

Each tool accepts structured inputs and returns JSON-compatible outputs suitable for LLM consumption and downstream automation.

Use Cases (concrete examples)

Debug a failed pull request from your editor: ask your MCP client to “show failing tests and failure logs for PR #123”, get test metadata and relevant logs, and receive suggested remediation steps.
Run a quick policy check before merging: use analyze_diff to scan the branch diff for CircleCI policy violations (e.g., disallowed workflows or resource usage) and get an actionable report.
Reduce CI cost: run find_underused_resource_classes to identify jobs with oversized resource classes, then generate recommended smaller configurations.
Investigate flaky tests: call find_flaky_tests for a project and timeframe, receive a ranked list of flaky tests with historical failure rates and most-affected jobs.
Trigger or rollback pipelines from chat: using run_pipeline or run_rollback_pipeline to start CI from within your AI assistant session, including parameterized pipelines.
Create and validate prompt templates: generate structured prompt templates and test cases using create_prompt_template and recommend_prompt_template_tests to improve AI-driven automation.

Getting Help and Contributing

See the project repository for docs, issues, and contribution guidelines: https://github.com/CircleCI-Public/mcp-server-circleci

If you’re integrating this server into a new MCP client, follow the MCP spec for server discovery and input schemas, and verify your environment variables and token permissions before starting.

CircleCI MCP Server for AI Workflow Integration