Skip to content
CircleCI MCP Server

CircleCI MCP Server

by CircleCI
Released
v0.20.0
Apache-2.0
Repository Docs npm
Developer Tools

Summary

CircleCI's official MCP server: pull build failure logs, hunt flaky tests, validate config, trigger and rerun pipelines, and roll back - in natural language from your IDE.

Features

  • Fetch build failure logs and job test results
  • Detect flaky tests from execution history
  • Validate CircleCI config and get fix guidance
  • Trigger pipelines, rerun workflows and run rollbacks
  • Find underused resource classes to cut compute spend
  • Download CircleCI Usage API data
  • Self-managed remote deployment for shared team use

Installation

Set up this MCP server in your favorite AI agent — copy a ready-made configuration below.

Any MCP-compatible agent

Most agents (Claude, Cursor, Windsurf, VS Code, and more) read a standard mcpServers configuration.

  1. Open your agent's MCP configuration file.
  2. Merge the snippet below into it, filling in the environment variables with your own values.
  3. Restart the agent — the "CircleCI MCP Server" tools will be available.
{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "<your-circleci-personal-api-token>",
        "CIRCLECI_BASE_URL": "https://circleci.com"
      }
    }
  }
}

Description

The CircleCI MCP Server puts your CI pipeline where your agent can read it. Instead of tabbing to the CircleCI web app to work out why a build went red, you ask in the editor and the agent fetches the failure logs, the test results and the config guidance it needs to propose a fix.

Tools
  • get_build_failure_logs - detailed failure logs from a build
  • get_latest_pipeline_status - status of the latest pipeline for a branch
  • get_job_test_results - test metadata and results for a job
  • find_flaky_tests - identify flaky tests from execution history (optionally written to a directory via FILE_OUTPUT_DIRECTORY)
  • config_helper - validate a CircleCI config and get guidance on it
  • run_pipeline - trigger a pipeline
  • rerun_workflow - rerun a workflow from the start or from the failed job
  • run_rollback_pipeline - trigger a rollback for a project
  • list_followed_projects, list_artifacts, list_component_versions
  • find_underused_resource_classes - spot jobs paying for more compute than they use
  • download_usage_api_data - pull data from the CircleCI Usage API
Running it

The usual setup is npx-based and needs Node.js 18 or newer plus a CircleCI personal API token in CIRCLECI_TOKEN; CIRCLECI_BASE_URL points at your CircleCI instance. A Docker image is available as a fallback. For teams, the project documents a self-managed remote server you deploy once (Kubernetes or Docker) with either per-developer or shared tokens, instead of every engineer running a local copy.

Configuration is documented for Cursor, Windsurf, VS Code Copilot, Claude, Amazon Q Developer (~/.aws/amazonq/mcp.json globally or .amazonq/mcp.json per workspace) and any other MCP-compatible client. Telemetry is described in the README. Apache-2.0 licensed and maintained by CircleCI-Public.

Covered in the Weekly

Related MCP Servers

MCP: Buildkite MCP Server

by Buildkite

Buildkite's official MCP server: query pipelines, builds, jobs, logs, test runs and flaky-test data from an agent, over a hosted OAuth endpoint or a self-run binary.

Developer Tools

MCP: Azure DevOps MCP Server

by Microsoft

Featured

Microsoft's official MCP server for Azure DevOps - work items, repos, pipelines, wikis, test plans and iterations, reachable from any MCP client in plain language.

Developer Tools

MCP: Qase MCP Server

by Qase

Featured

Qase test management over MCP: 36 task-oriented tools for cases, runs, results, defects and QQL search, hosted at mcp.qase.io or self-run with your own API token.

Developer Tools

MCP: Currents MCP Server

by Currents

Gives coding agents your CI test results from Currents: failed runs, flaky tests, error trends, quarantine rules and Playwright trace evidence.

Developer Tools
Browse all MCP servers →