home / mcp / circleci mcp server

CircleCI MCP Server

Provides an MCP server to manage CircleCI tasks via MCP clients using tokens and standard endpoints.

Installation

Add the following to your MCP client configuration file.

Configuration

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

CircleCI MCP Server enables natural language control of CircleCI through the Model Context Protocol (MCP). You can use MCP-enabled clients to ask for build logs, run pipelines, check statuses, and perform a wide range of CircleCI actions by talking in plain language to the server. This guide walks you through practical usage, installation steps, and important configurations so you can set up and operate MCP with CircleCI quickly and securely.

How to use

Connect an MCP-enabled client such as Cursor IDE, Windsurf, Copilot, or any MCP-supported client to the CircleCI MCP Server. You can perform actions like finding the latest failed pipeline and retrieving logs, checking the status of the latest pipeline for a branch, or examining test results directly from your IDE or editor.

How to install

Prerequisites you need before installing the CircleCI MCP Server:

- Node.js version 18 or newer

- A CircleCI Personal API Token with read access to your projects

Cursor

{
  "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" // Optional - required for on-prem customers only
      }
    }
  }
}

Cursor in Docker

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      }
    }
  }
}

Cursor self-managed remote MCP server

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token", 
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "servers": {
    "circleci-mcp-server-remote": {
      "url": "http://your-circleci-remote-mcp-server-endpoint:8000/mcp"
    }
  }
}

VS Code

Install CircleCI MCP Server for VS Code in the MCP configuration file for your project.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

VS Code in Docker

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

Self-managed remote MCP server for VS Code

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

Claude Desktop

{
  "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" // Optional - required for on-prem customers only
      }
    }
  }
}

Claude Desktop location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\CLAUDE\claude_desktop_config.json

Claude Desktop Docker

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      }
    }
  }
}

Claude Desktop self-managed remote

#!/bin/bash
export CIRCLECI_TOKEN="your-circleci-token"
npx mcp-remote http://your-circleci-remote-mcp-server-endpoint:8000/mcp --allow-http

{
  "mcpServers": {
    "circleci-remote-mcp-server": {
      "command": "/full/path/to/circleci-remote-mcp.sh"
    }
  }
}

Claude Code

Install CircleCI MCP Server for Claude Code using NPX or Docker.

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest

Claude Code Docker

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com -- docker run --rm -i -e CIRCLECI_TOKEN -e CIRCLECI_BASE_URL circleci:mcp-server-circleci

Claude Code Remote

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx mcp-remote http://your-circleci-remote-mcp-server-endpoint:8000/mcp --allow-http

Windsurf

{
  "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" // Optional - required for on-prem customers only
      }
    }
  }
}

Windsurf Docker

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      }
    }
  }
}

Windsurf self-managed remote MCP server

{
  "mcpServers": {
    "circleci": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://your-circleci-remote-mcp-server-endpoint:8000/mcp",
        "--allow-http"
      ],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Amazon Q Developer

MCP client configuration files for Amazon Q Developer can be global or workspace specific.

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      },
      "timeout": 60000
    }
  }
}

Amazon Q Developer in the IDE

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      },
      "timeout": 60000
    }
  }
}

Amazon Q Developer in the IDE – Remote

{
  "mcpServers": {
    "circleci-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://your-circleci-remote-mcp-server-endpoint:8000/mcp",
        "--allow-http"
      ],
      "timeout": 60000
    }
  }
}

Windsurf – Additional examples

All client integrations listed above provide multiple ways to connect. Use the option that matches your workflow and editor.

Available tools

get_build_failure_logs

Retrieves detailed failure logs from CircleCI builds; supports multiple usage modes including by project slug/branch, by direct URL, or from local project context.

find_flaky_tests

Identifies flaky tests by analyzing test history; supports multiple input methods and optional file output mode.

get_latest_pipeline_status

Fetches the status of the latest CircleCI pipeline for a given branch with detailed workflow information.

get_job_test_results

Retrieves test metadata for CircleCI jobs to analyze test outcomes from various contexts.

config_helper

Validates and guides CircleCI configuration files for syntax, semantics, and best practices.

create_prompt_template

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

recommend_prompt_template_tests

Produces test case scenarios to validate prompt templates across inputs.

list_followed_projects

Lists all CircleCI projects you follow, including projectSlug details for subsequent operations.

run_pipeline

Triggers a CircleCI pipeline with multiple input methods, returning a monitorable URL.

run_rollback_pipeline

Triggers a rollback using a defined pipeline or reruns a workflow to revert to a previous version.

rerun_workflow

Reruns a CircleCI workflow from its start or from a failed job, returning a monitor URL.

analyze_diff

Analyzes git diffs against cursor rules to identify violations with explanations.

list_component_versions

Lists all component versions in an environment with deployment details for rollback decisions.

download_usage_api_data

Downloads usage data from the CircleCI Usage API for an organization, supporting date parsing.

find_underused_resource_classes

Analyzes usage data to find resources with low CPU/RAM usage for optimization.