CircleCI MCP Server

Name: CircleCI MCP Server
Author: CircleCI-Public

@CircleCI-Public

About CircleCI MCP Server

A specialized server implementation for the Model Context Protocol (MCP) designed to integrate with CircleCI's development workflow. This project serves as a bridge between CircleCI's infrastructure and the Model Context Protocol, enabling enhanced AI-powered development experien

#mcp-server #modelcontextprotocol

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "mcp-server-circleci": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli",
        "install",
        "@CircleCI-Public/mcp-server-circleci",
        "--client",
        "claude"
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is CircleCI MCP Server?

A Model Context Protocol (MCP) server that integrates CircleCI with MCP-compatible clients (Cursor, Windsurf, Claude, Amazon Q Developer CLI, etc.), enabling natural‑language interaction with CircleCI pipelines, workflows, tests, and configuration. Built for developers who want to manage CircleCI projects without leaving their IDE.

How to use CircleCI MCP Server?

Requires a CircleCI Personal API token and either Node.js ≥18 (with pnpm) for the NPX runner, or Docker. Add the server to your MCP client’s config (e.g., mcpServers in Cursor) using the command npx -y @circleci/mcp-server-circleci@latest or the Docker image circleci/mcp-server-circleci. Set the CIRCLECI_TOKEN environment variable; optionally set CIRCLECI_BASE_URL for on‑premises customers and MAX_MCP_OUTPUT_LENGTH (default 50000).

Key features of CircleCI MCP Server?

Analyze git diffs against cursor rules for violations
Validate and get guidance for your CircleCI configuration
Download usage data from the CircleCI Usage API
Identify flaky tests from test execution history
Find jobs with underused compute resources
Retrieve build failure logs and job test results
Get the latest pipeline status for a branch
List artifacts, followed projects, and component versions
Rerun workflows from start or from the failed job
Trigger pipelines and rollback pipelines

Use cases of CircleCI MCP Server?

Debug build failures by pulling failure logs directly from your IDE
Optimise resource usage by detecting under‑utilised compute classes
Automate pipeline re‑runs and rollbacks during incident response
Review flaky test patterns without switching to the CircleCI dashboard
Validate CircleCI configuration files before committing changes

FAQ from CircleCI MCP Server

What runtime dependencies are required?

Node.js version 18 or later and pnpm (for NPX runs) or Docker. A CircleCI Personal API token is mandatory.

How do I get a CircleCI API token?

Create a Personal API token at https://app.circleci.com/settings/user/tokens. See the official documentation for details.

Can I use this server with an on‑premises CircleCI installation?

Yes. Set the CIRCLECI_BASE_URL environment variable to your on‑premises instance URL.

What does `MAX_MCP_OUTPUT_LENGTH` control?

It limits the maximum output length for MCP responses. The default is 50,000 characters, and it is optional.

Which MCP clients are supported?

Cursor, VS Code, Claude Desktop, Claude Code, Windsurf, Amazon Q Developer CLI, and any MCP‑compatible client. The README provides per‑client configuration examples.