CircleCI MCP Server

Official CircleCI MCP server for interacting with pipelines, fetching build failure logs, finding flaky tests, and managing CI/CD workflows via natural language.

Developer Tools by CircleCI API Key active

GitHub Docs npm: @circleci/mcp-server-circleci

Overview

The CircleCI MCP Server is the official Model Context Protocol implementation maintained by CircleCI-Public. It lets developers interact with CircleCI infrastructure using natural language directly from compatible AI clients and IDEs (Cursor, VS Code, Claude Desktop, Claude Code, Windsurf, Amazon Q Developer). It is designed to streamline debugging, test analysis, and pipeline operations without leaving the editor.

The server exposes 18 tools covering build failure log retrieval, flaky test detection, test result analysis, configuration validation, pipeline triggering and rerunning, rollbacks, artifact listing, usage data export, and prompt-template testing for AI applications. It also includes cost optimization tooling like find_underused_resource_classes to identify wasted compute spend.

Authentication uses a CircleCI Personal API Token with read access to your projects. The server can be run locally via NPX or Docker, or as a remote HTTP MCP server, making it flexible for both individual developers and teams that want a shared deployment.

Tools

Tool	Description
`analyze_diff`	Checks code changes against repository rules for violations.
`config_helper`	Validates CircleCI YAML configuration and provides recommendations.
`create_prompt_template`	Generates structured prompt templates for AI applications.
`download_usage_api_data`	Exports CircleCI usage metrics as CSV.
`find_flaky_tests`	Identifies unreliable tests using execution history.
`find_underused_resource_classes`	Analyzes compute resource utilization to surface cost-saving opportunities.
`get_build_failure_logs`	Retrieves detailed failure information from failed builds.
`get_job_test_results`	Extracts test metadata and results from a job.
`get_latest_pipeline_status`	Returns current pipeline state and timing.
`list_artifacts`	Shows build output files and download URLs.
`list_component_versions`	Displays available component versions for rollback operations.
`list_followed_projects`	Enumerates CircleCI projects the user follows.
`recommend_prompt_template_tests`	Generates test scenarios for prompt templates.
`rerun_workflow`	Restarts a workflow from the beginning or from the point of failure.
`run_evaluation_tests`	Executes prompt testing pipelines.
`run_pipeline`	Triggers a pipeline execution.
`run_rollback_pipeline`	Initiates a rollback procedure.

Setup Guide

Prerequisites

A CircleCI Personal API Token from https://app.circleci.com/settings/user/tokens
Node.js >= 18.0.0 (for NPX install) or Docker (for container install)

Option 1: NPX (recommended for local use)

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json or Cursor mcp.json):

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

Option 2: Docker

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

Option 3: Remote HTTP server

{
  "servers": {
    "circleci-mcp-server-remote": {
      "url": "http://your-endpoint:8000/mcp"
    }
  }
}

Environment variables

CIRCLECI_TOKEN (required): Personal API token with read access to your projects.
CIRCLECI_BASE_URL (optional, default https://circleci.com): Use this for CircleCI Server installs.
MAX_MCP_OUTPUT_LENGTH (optional, default 50000): Limits response size.
DISABLE_TELEMETRY (optional, default false): Disables usage metrics.

Supported clients: Cursor, VS Code, Claude Desktop, Claude Code, Windsurf, Amazon Q Developer, and Smithery (automated install).

Use Cases

Pull the failure logs from the latest failed pipeline on a branch and ask the agent to propose a fix.
Detect flaky tests across recent runs and generate a triage list with find_flaky_tests.
Validate or lint a .circleci/config.yml using config_helper before pushing changes.
Identify underused resource classes and rightsize jobs to cut CI compute costs.
Trigger, rerun, or roll back pipelines (including rerun from failed step) from inside the IDE.

Example Prompts

"Find the latest failed pipeline on my branch and summarize the root cause from the logs."
"List flaky tests on the main branch of my-org/my-repo in the last 30 days."
"Validate this CircleCI config file and suggest improvements."
"Show me jobs in my project that have underused resource classes so I can save money."
"Rerun the failed workflow from the point of failure and notify me when it completes."

Pros

Official server maintained by CircleCI-Public, so tool coverage tracks the platform.
Broad capability set (18 tools) spanning debugging, testing, cost, and pipeline control.
Multiple deployment options: NPX, Docker, and remote HTTP, with support for many MCP clients.
Works against self-hosted CircleCI Server via CIRCLECI_BASE_URL.

Limitations

Requires a CircleCI Personal API Token; team-wide rollouts need careful token management.
Default MAX_MCP_OUTPUT_LENGTH of 50,000 can truncate very large log outputs.
Some tools (rollback, prompt-template evaluation) assume specific CircleCI workflows that not every project uses.

Alternatives

GitHub Actions MCP servers (community implementations) for repos using GitHub Actions instead of CircleCI.
GitLab MCP server for GitLab CI/CD pipelines.
Generic shell/Bash MCP servers paired with the circleci CLI for ad hoc scripting.