CircleCI MCP Server

Official

Integrate CircleCI development workflows with the Model Context Protocol for AI-powered development.

How to install ↓ Compare GitHub source repository ↗

Category: Dev Tools #339 of 438
Stars: ★ 93 Popular
Transport: stdio (local process)
Runtime: Node.js 18+ · Docker
Credentials: API key / credential required
License: Other / unspecified
Last commit: 2 months ago
Tools: 13

42FMRS · D

A feature-rich MCP server for CircleCI, covering everything from configuration validation to pipeline triggering. However, it is officially deprecated, so migration to CircleCI's hosted MCP or CLI MCP is advised. Easy to install and compatible with major MCP clients.

Strongest · Documentation 10/20 Weakest · Reliability 6/20

Reliability

6/20

Security and permissions

10/20

Maintenance

8/20

Documentation

10/20

Setup experience

8/20

Why each score

Reliability 6/20: No actual test files or CI workflows were found in the source listing; only README and metadata were provided. The server's key paths (init handshake, tool behavior) are not verifiable from static evidence. README lists 13 tools with descriptions, but no tests or CI to confirm they match real behavior. Deductions for missing execution evidence.
Security and permissions 10/20: Security design is thoughtful: remote mode defaults to requiring request tokens, shared-token mode requires explicit opt-out with a risk acknowledgment environment variable, and file I/O is restricted to allowed roots. However, no confirmation mechanism for destructive operations (e.g., rerun_workflow, run_pipeline) was documented, and installation examples use npx -y which can execute arbitrary versions. No red-line issues detected; score mid-high due to good design but incomplete confirmation for state-changing actions.
Maintenance 8/20: Repository is marked as deprecated and will be archived, which is a negative signal for future maintenance. However, it has an Apache 2.0 license, versioned npm releases, and appears to have recent activity (based on README mentioning latest guides). No public issue response metrics or security-response channel evident from static data. Deducted for deprecation and unverified update path.
Documentation 10/20: Documentation is exceptional: covers installation for multiple clients, remote deployment modes, environment variables, tool details, troubleshooting, and development setup. It also discloses security limitations (e.g., DNS-rebinding protection is not authentication). Static evidence supports high quality, though no manual or API reference exists for all parameters.
Setup experience 8/20: Setup is clear with step-by-step configs for npx and Docker across many IDEs, plus remote server deployment instructions. Requires Node.js, pnpm, and Docker dependencies, increasing complexity. No verifiable CI/test evidence from source to confirm setup works as described. Deducted for external dependencies and lack of execution verification.

Static review · not runListed 2026-08-07

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesWrites / deletes local filesUses the networkChanges third-party account data

Best for

Developers using MCP-compatible clients like Cursor, VS Code, Claude Desktop.
Teams that want to manage CircleCI pipelines seamlessly within their IDE.
Developers needing quick diagnostics for build failures and test issues.

Not for

Users needing the latest features and security updates, as the package is deprecated and unmaintained.
Users seeking a hosted solution; CircleCI's hosted MCP server is recommended.
Users needing public remote access unless deploying a self-managed remote server with extra security.

Required permissions

Requires a CircleCI Personal API token (CIRCLECI_TOKEN) with read access to projects.
In remote mode, requires configuring allowed hosts (MCP_ALLOWED_HOSTS) and authentication.
File-related tools may read/write files; set MCP_FILE_OUTPUT_ROOTS to restrict root directories.

Risks and side effects

Token exposure: if the personal or shared token leaks, unauthorized operations may occur.
Deprecation risk: the server is no longer maintained, potentially with security or compatibility issues.
Remote mode risk: if authentication is disabled (REQUIRE_REQUEST_TOKEN=false), anyone reaching the port can act on the server.

Setup

Before you start

Runtime：Node.js 18+ · Docker

CIRCLECI_TOKEN requiredsecret CircleCI Personal API Token, created at app.circleci.com/settings/user/tokens.

Other optional settings (10)

CIRCLECI_BASE_URL optional CircleCI API base URL, default https://circleci.com; only needed for on-prem.

MAX_MCP_OUTPUT_LENGTH optional Maximum MCP response output length, default 50000.

REQUIRE_REQUEST_TOKEN optional Whether remote mode requires a per-request token; enabled by default.

MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS optional Explicit acknowledgment needed to run unauthenticated shared-token mode on a non-loopback bind.

MCP_ALLOWED_HOSTS optional Comma-separated additional allowed Host headers; required for public remote deployments.

MCP_ALLOWED_ORIGINS optional Comma-separated additional allowed Origin headers; only needed for direct browser access.

MCP_BIND_HOST optional Network interface to bind in remote mode, default 0.0.0.0.

MCP_FILE_OUTPUT_ROOTS optional Extra directories file-reading/writing tools may access.

DISABLE_TELEMETRY optional Set to true to opt out of usage metrics export.

FILE_OUTPUT_DIRECTORY optional Directory used when find_flaky_tests runs in file output mode.

Create a CircleCI Personal API token at https://app.circleci.com/settings/user/tokens.
Ensure Node.js >= 18 and pnpm are installed.
Add the following JSON to your MCP client config (example for 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",
"MAX_MCP_OUTPUT_LENGTH": "50000"
}
}
}
}4. Restart your IDE and start using.

.cursor/mcp.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"
      }
    }
  }
}

Shown for Cursor. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json

{
  "servers": {
    "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"
      }
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com -e MAX_MCP_OUTPUT_LENGTH=50000 -- npx -y @circleci/mcp-server-circleci@latest

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

Confirm tools like config_helper and list_followed_projects appear in the client's tool list, then ask 'List my followed CircleCI projects' to prove the token works.

Troubleshooting

Clear npx cache: npx clear-npx-cache && npm cache clean --force.
Ensure using @latest version and fully restart your IDE.
Check that CIRCLECI_TOKEN is correct and has access to projects.
For network issues, verify CIRCLECI_BASE_URL is set to https://circleci.com or configure npm proxy.
For remote mode, ensure MCP_ALLOWED_HOSTS is set to your domain, otherwise you'll get 403.

Things to try

Once connected, you can ask your AI assistant things like:

List my followed CircleCI projects
Get the build failure logs for the latest failed build on the main branch
Validate my .circleci/config.yml configuration
Rerun the failed workflow from the failed job

Tools 13

config_helper read-only

Validate and get guidance for your CircleCI configuration.

download_usage_api_data read-only

Download usage data from the CircleCI Usage API.

find_flaky_tests read-only

Identify flaky tests by analyzing test execution history.

find_underused_resource_classes read-only

Find jobs with underused compute resources.

get_build_failure_logs read-only

Retrieve detailed failure logs from CircleCI builds.

get_job_test_results read-only

Retrieve test metadata and results for CircleCI jobs.

get_latest_pipeline_status read-only

Get the status of the latest pipeline for a branch.

list_artifacts read-only

List artifacts produced by a CircleCI job.

Show 5 more tools

list_component_versions read-only

List all versions for a CircleCI component.

list_followed_projects read-only

List all CircleCI projects you're following.

rerun_workflow writes

Rerun a workflow from start or from the failed job.

run_pipeline writes

Trigger a pipeline to run.

run_rollback_pipeline destructive

Trigger a rollback for a project.

Use cases

Query pipeline status, build logs, test results, etc., via natural language.

Trigger pipeline runs or rerun workflows directly from your IDE.

Analyze test stability, resource utilization, and optimize CI/CD costs.

Supported clients

Cursor

VS Code

Claude Desktop

Claude Code

Windsurf

Amazon Q Developer

Listed from the project's documentation, not tested by this site.

Overview

The CircleCI MCP Server is a specialized server implementation for the Model Context Protocol (MCP) designed to integrate with CircleCI's development workflow. It bridges CircleCI's infrastructure and MCP, enabling enhanced AI-powered development experiences. The server offers tools for configuration validation, test analysis, build logs, artifacts, pipeline triggering, and more. Note: The package is deprecated and no longer receiving feature work; migrate to CircleCI's hosted MCP server or CLI MCP.

Similar servers

Context7 80 · B

Upstash's official server providing up-to-date third-party library docs for AI coding assistants

★ 62.9k · Tools 2 Compare with this →

NPM Sentinel MCP Server 79 · B

AI-powered NPM package analysis MCP server

★ 18 · Tools 19 Compare with this →

MartinLoop MCP Server 79 · B

An independent control layer that gives AI coding agents budgets, brakes, and receipts

★ 410 Compare with this →

GitHub MCP Server 76 · B

GitHub's official MCP server for managing repos, issues, PRs, and workflows via natural language

★ 33.5k · Tools 15 Compare with this →

Compare with other MCP servers

Source revision c47ce3fa6f6f Data synced 2026-10-12 Read the FMRS scoring method