Yes. The server is free and open source under the CircleCI-Public organization; you only need a CircleCI account and a personal API token scoped to the projects you want the agent to reach.

Does it support remote/OAuth?

No. It runs locally over stdio via npx and authenticates with a CircleCI personal API token in CIRCLECI_TOKEN; there is no hosted remote endpoint or OAuth flow. Self-hosted CircleCI server is supported via CIRCLECI_BASE_URL.

Does it work with self-hosted CircleCI server?

Yes. Set CIRCLECI_BASE_URL to your CircleCI server URL; it defaults to https://circleci.com for the cloud product.

CircleCI MCP server

OfficialCircleCI84Config last verified Jun 1, 2026

CircleCI's official MCP server: pull build failure logs, find flaky tests, validate config, and run pipelines from an agent.

The CircleCI MCP Server is CircleCI's official integration that lets an AI agent reach into your continuous integration pipelines. Its headline use is failure triage: the agent fetches detailed build failure logs for a broken job, then proposes a fix in the same conversation. Beyond logs it can identify flaky tests by analyzing historical test execution, inspect job test results, list artifacts, surface underused compute resource classes to cut spend, and report the latest pipeline status for a branch.

The server also drives pipelines directly: trigger a run, rerun a workflow from the start or from the first failed job, and trigger a rollback for a project. A config_helper tool validates CircleCI YAML and returns guidance, and a set of prompt-template tools help build and test AI prompt evaluations inside CircleCI. It runs locally over stdio via npx and authenticates with a CircleCI personal API token in CIRCLECI_TOKEN, with CIRCLECI_BASE_URL available for self-hosted CircleCI server installations.

Quick install

Copy-paste configs are provided for all 8 supported clients. Pick your client below.

Add to ~/.claude.json

~/.claude.json

json

{
  "mcpServers": {
    "circleci": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "<CIRCLECI_TOKEN>",
        "CIRCLECI_BASE_URL": "<CIRCLECI_BASE_URL>"
      }
    }
  }
}

Or via CLI

bash

claude mcp add circleci -- npx -y @circleci/mcp-server-circleci@latest

Step-by-step guides

Available tools

Tool	Description
get_build_failure_logs	Retrieves detailed failure logs from a CircleCI build for triage.
find_flaky_tests	Identifies flaky tests by analyzing test execution history.
get_latest_pipeline_status	Gets the status of the latest pipeline for a branch.
get_job_test_results	Retrieves test metadata and results for CircleCI jobs.
config_helper	Validates a CircleCI configuration and returns guidance on it.
run_pipeline	Triggers a pipeline to run.
rerun_workflow	Reruns a workflow from the start or from the first failed job.
run_rollback_pipeline	Triggers a rollback pipeline for a project.
list_followed_projects	Lists all CircleCI projects you are following.
list_artifacts	Lists the artifacts produced by a CircleCI job.
list_component_versions	Lists all versions for a CircleCI component.
find_underused_resource_classes	Finds jobs running on underused compute resource classes.
download_usage_api_data	Downloads usage data from the CircleCI Usage API.
analyze_diff	Analyzes a git diff against cursor rules for violations.
create_prompt_template	Generates a structured prompt template for AI applications.
recommend_prompt_template_tests	Generates recommended test cases for a prompt template.
run_evaluation_tests	Runs evaluation tests on a CircleCI pipeline.

Required configuration

CIRCLECI_TOKENRequired
Your CircleCI personal API token, used to authenticate API calls.
CIRCLECI_BASE_URLOptional
Base URL for self-hosted CircleCI server. Defaults to https://circleci.com for the cloud.
MAX_MCP_OUTPUT_LENGTHOptional
Maximum output length for MCP responses. Defaults to 50000.

What you can do with it

Triage a red build without leaving the editor

The agent fetches the failure logs for the broken job, reads the stack trace, and proposes a code fix in the same conversation, turning a CI failure notification into an actionable diff.

Hunt down flaky tests

Ask the agent which tests are flaky and it analyzes execution history to surface the unstable specs, so you can quarantine or fix them before they erode trust in the suite.

FAQ

Is it free?: Yes. The server is free and open source under the CircleCI-Public organization; you only need a CircleCI account and a personal API token scoped to the projects you want the agent to reach.
Does it support remote/OAuth?: No. It runs locally over stdio via npx and authenticates with a CircleCI personal API token in CIRCLECI_TOKEN; there is no hosted remote endpoint or OAuth flow. Self-hosted CircleCI server is supported via CIRCLECI_BASE_URL.
Does it work with self-hosted CircleCI server?: Yes. Set CIRCLECI_BASE_URL to your CircleCI server URL; it defaults to https://circleci.com for the cloud product.

← Browse all devops-ci servers