home / mcp / circleci mcp server

CircleCI MCP Server

Connect CircleCI with MCP clients to run queries, fetch logs, statuses, and test results from natural language prompts.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ampcome-mcps-circleci-mcp": {
      "url": "http://your-circleci-remote-mcp-server-endpoint:8000/mcp",
      "headers": {
        "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
        "CIRCLECI_BASE_URL": "https://circleci.com"
      }
    }
  }
}

You can use CircleCI MCP Server to control CircleCI from natural language through any MCP-compatible client. By connecting to CircleCI, you can ask for build logs, pipeline status, test results, and more, all within your IDE, editor, or tooling that speaks MCP.

How to use

Connect your MCP client (Cursor IDE, Windsurf, Copilot, Claude, or any MCP-enabled tool) to CircleCI MCP Server. You provide your CircleCI API token and the base URL if you are using an on‑prem installation. Then you can ask for intelligent actions such as getting logs for the latest failed pipeline, running pipelines, or inspecting flaky tests. Use natural language prompts like: “Get logs for the latest failed build on main” or “Show me the status of the latest pipeline for my project.” The server translates your requests into CircleCI API calls and returns structured results that you can view in your editor or IDE.

What you can accomplish with the server

Retrieve detailed failure logs from CircleCI builds with contextual information like job names and step details
Identify flaky tests by analyzing test execution history
Check the status of the latest pipeline and its workflows
Fetch test results for CircleCI jobs with timestamps and outcomes
Validate your CircleCI configurations and receive guidance on adjustments
Trigger pipelines or roll back deployments from your preferred client

Examples of workflows you can perform

Use the server to interact with CircleCI in a more natural, context-aware way. For example, you can ask to find the latest failed pipeline on your current branch and retrieve logs, or request the status of the most recent pipeline for a given project and branch. You can also pull test results, check for flaky tests, or validate the CircleCI config from within your editing environment.

Available tools

get_build_failure_logs

Retrieves detailed failure logs from CircleCI builds, with job names, step details, and failure messages.

find_flaky_tests

Identifies flaky tests by analyzing test execution history and provides detailed results.

get_latest_pipeline_status

Fetches the status of the latest CircleCI pipeline for a given branch, including workflow statuses and durations.

get_job_test_results

Retrieves test metadata for CircleCI jobs, including summary, failed tests, and runtimes.

config_helper

Validates and guides CircleCI configuration for correctness and best practices.

create_prompt_template

Generates structured prompt templates from feature requirements for AI-enabled apps.

recommend_prompt_template_tests

Creates test cases to validate prompt templates under various scenarios.

list_followed_projects

Lists CircleCI projects you follow and returns project names with their project Slugs.

run_pipeline

Triggers a CircleCI pipeline for a selected project and branch, returning a monitorable link.

run_rollback_pipeline

Guides and executes a rollback pipeline for a CircleCI project with interactive prompts.

rerun_workflow

Reruns a CircleCI workflow from its start or from a failed job and returns a monitor link.

analyze_diff

Analyzes git diffs against cursor rules to identify violations and quality issues.