CircleCI MCP Server
Connect your AI assistant to your CircleCI data to debug failures, analyze test results, and improve pipelines using natural language.
CI/CD context for AI tools
The CircleCI MCP server makes your build system understandable by AI tools like Cursor, Claude Code, Windsurf, and more. It’s built on the Model Context Protocol (MCP), a lightweight standard that allows LLM-powered agents to fetch structured data from external systems.
By connecting to the CircleCI MCP Server, agents gain real-time visibility into:
- Build logs and test outputs
- Pipeline statuses
- Recent configuration changes
- Workflow performance metrics
That means instead of digging through job logs or dashboard UIs, you can ask:
why did my last build fail?
and get all the context you need to fix the issue and keep moving without breaking stride.
Turn build data into action
Once installed, the MCP server makes your CI/CD data accessible through natural language. LLM-based tools can:
- Diagnose failing builds
Get structured error summaries and logs. - Trace failures to recent changes
Connect regressions to commits, diffs, or workflows. - Spot flaky tests
Surface instability patterns from test history. - Recommend improvements
Suggest config or timing optimizations in context. - Bring CI data into your editor
Use LLM tools to reason through builds without switching tabs.
With access to both code and build context, these tools can help you fix bugs faster, ship changes with confidence, and stay focused on the work that matters.
Get started with MCP
The CircleCI MCP Server runs locally and integrates with a variety of editors and LLM development tools.
Below are ready-to-use configuration examples to help you install the MCP server in your preferred environment.
Prerequisites
Before setting up your IDE, make sure you have the following:
- CircleCI Personal API Token (PAT):
- Go to User Settings > Personal API Tokens
- Click Create New Token
- Copy and store it securely — you’ll use it as
CIRCLECI_TOKENduring setup
- For NPX installation:
- pnpm package manager
- Node.js version ≥ 18.0.0
- For Docker installation:
Configuration instructions
Available tools
From accelerating AI-driven development to orchestrating agentic workflows, each tool exposed by the MCP server equips AI developers with structured CI/CD context for faster, more reliable release cycles.
| Tool | Uses |
|---|---|
analyze_diff |
Catch rule violations in your diff before code review |
config_helper |
Fix config issues before they break your pipeline |
create_prompt_template |
Generate prompts that support consistent AI behavior |
download_usage_api_data |
Export CircleCI usage data for cost and capacity analysis |
find_flaky_tests |
Identify and troubleshoot unstable tests |
find_underused_resource_classes |
Find jobs with low CPU/RAM utilization for downsizing |
get_build_failure_logs |
Debug and resolve failed builds faster |
get_job_test_results |
Understand and fix test failures and performance issues |
get_latest_pipeline_status |
Monitor and act on pipeline health |
list_artifacts |
Find and download artifacts produced by a job |
list_component_versions |
View deployed versions and pick rollback targets |
list_followed_projects |
Find projects you follow and their projectSlug |
recommend_prompt_template_tests |
Test and improve prompt reliability |
rerun_workflow |
Rerun workflows from the beginning or from a failed job |
run_evaluation_tests |
Run prompt evaluation tests on a CircleCI pipeline |
run_pipeline |
Trigger builds while staying in your editor |
run_rollback_pipeline |
Roll back faulty deployments with a single command |
Learn more
Get started with the CircleCI MCP Server, dive into examples, or keep up with platform updates:
- Project repository – Source code, issues, and contribution guide.
- MCP cookbook – Prompt examples and tool usage patterns.
- Blog post: Introducing the CircleCI MCP Server – Design background and use cases.
- CircleCI changelog – See the latest platform updates and feature releases.