Name: CircleCI
Author: CircleCI

CircleCI MCP Server

Model Context Protocol (MCP) is a new, standardized protocol for managing context between large language models (LLMs) and external systems. In this repository, we provide an MCP Server for CircleCI.

Use Cursor, Windsurf, Copilot, Claude, or any MCP-compatible client to interact with CircleCI using natural language — without leaving your IDE.

Tools

Tool	Description
`analyze_diff`	Analyze git diffs against cursor rules for violations
`config_helper`	Validate and get guidance for your CircleCI configuration
`create_prompt_template`	Generate structured prompt templates for AI applications
`download_usage_api_data`	Download usage data from the CircleCI Usage API
`find_flaky_tests`	Identify flaky tests by analyzing test execution history
`find_underused_resource_classes`	Find jobs with underused compute resources
`get_build_failure_logs`	Retrieve detailed failure logs from CircleCI builds
`get_job_test_results`	Retrieve test metadata and results for CircleCI jobs
`get_latest_pipeline_status`	Get the status of the latest pipeline for a branch
`list_artifacts`	List artifacts produced by a CircleCI job
`list_component_versions`	List all versions for a CircleCI component
`list_followed_projects`	List all CircleCI projects you're following
`recommend_prompt_template_tests`	Generate test cases for prompt templates
`rerun_workflow`	Rerun a workflow from start or from the failed job
`run_evaluation_tests`	Run evaluation tests on a CircleCI pipeline
`run_pipeline`	Trigger a pipeline to run
`run_rollback_pipeline`	Trigger a rollback for a project

Installation

Team / centralized deployment: To run one shared remote server for your org (Kubernetes, Docker, etc.) with per-developer or shared CircleCI tokens, see Self-Managed Remote MCP Server.

<details> <summary>Cursor</summary>

Prerequisites:

CircleCI Personal API token (learn more)
NPX: Node.js >= v18 and pnpm
Docker: Docker

Using NPX in a local MCP Server

Add the following to your Cursor MCP config:

{
  "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",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

CIRCLECI_BASE_URL is optional — required for on-prem customers only. MAX_MCP_OUTPUT_LENGTH is optional — maximum output length for MCP responses (default: 50000).

Using Docker in a local MCP Server

Add the following to your Cursor MCP config:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Using a Self-Managed Remote MCP Server

See Self-Managed Remote MCP Server. Use the per-user client configuration and add it to your Cursor MCP config (Cursor Settings → MCP).

</details> <details> <summary>VS Code</summary>

Prerequisites:

CircleCI Personal API token (learn more)
NPX: Node.js >= v18 and pnpm
Docker: Docker

Using NPX in a local MCP Server

Add the following to .vscode/mcp.json in 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}"
      }
    }
  }
}

💡 Inputs are prompted on first server start, then stored securely by VS Code.

Using Docker in a local MCP Server

Add the following to .vscode/mcp.json in 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": "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}"
      }
    }
  }
}

Using a Self-Managed Remote MCP Server

See Self-Managed Remote MCP Server. Use the per-user client configuration in .vscode/mcp.json.

</details> <details> <summary>Claude Desktop</summary>

Prerequisites:

CircleCI Personal API token (learn more)
NPX: Node.js >= v18 and pnpm
Docker: Docker

Using NPX in a local MCP Server

Add the following to your claude_desktop_config.json:

{
  "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",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Using Docker in a local MCP Server

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Using a Self-Managed Remote MCP Server

See Self-Managed Remote MCP Server. Create a wrapper script as shown in Claude Desktop and CLI clients, then point your claude_desktop_config.json at it.

To find or create your config file, open Claude Desktop settings, click Developer in the left sidebar, then click Edit Config. The config file is located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

For more information: https://modelcontextprotocol.io/quickstart/user

</details> <details> <summary>Claude Code</summary>

Prerequisites:

CircleCI Personal API token (learn more)
NPX: Node.js >= v18 and pnpm
Docker: Docker

Using NPX in a local MCP Server

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

Using Docker in a local MCP Server

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

Using a Self-Managed Remote MCP Server

See Self-Managed Remote MCP Server and the Claude Code client setup there.

</details> <details> <summary>Windsurf</summary>

Prerequisites:

CircleCI Personal API token (learn more)
NPX: Node.js >= v18 and pnpm
Docker: Docker

Using NPX in a local MCP Server

Add the following to your Windsurf mcp_config.json:

{
  "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",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Using Docker in a local MCP Server

Add the following to your Windsurf mcp_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Using a Self-Managed Remote MCP Server

See Self-Managed Remote MCP Server. Use the per-user client configuration in your Windsurf mcp_config.json.

For more information: https://docs.windsurf.com/windsurf/mcp

</details> <details> <summary>Amazon Q Developer CLI</summary>

Prerequisites:

CircleCI Personal API token (learn more)
NPX: [Node.js >= v

…

CircleCI

Installation

Configuration

How to use

README

CircleCI MCP Server

Tools

Installation

Using NPX in a local MCP Server

Using Docker in a local MCP Server

Using a Self-Managed Remote MCP Server

Using NPX in a local MCP Server

Using Docker in a local MCP Server

Using a Self-Managed Remote MCP Server

Using NPX in a local MCP Server

Using Docker in a local MCP Server

Using a Self-Managed Remote MCP Server

Using NPX in a local MCP Server

Using Docker in a local MCP Server

Using a Self-Managed Remote MCP Server

Using NPX in a local MCP Server

Using Docker in a local MCP Server

Using a Self-Managed Remote MCP Server

You might also like