CircleCI Integration Service via MCP

The Model Context Protocol (MCP) establishes a standardized framework for facilitating communication between sophisticated language models (LLMs) and external operational systems. This repository supplies the dedicated MCP Server implementation tailored for integration with the CircleCI platform.

This architecture empowers MCP-compatible clients (such as Cursor IDE, Windsurf, Copilot, or other supported agents) to leverage plain language queries to manage CI/CD workflows, for instance:

• "Retrieve logs from the most recent pipeline failure on my current feature branch" See integration guide for Cursor IDE

Visual demonstration asset link

Prerequisites

• A valid CircleCI Personal API Access Key. Obtainable via the CircleCI interface. Token generation documentation or Direct access link.

For setup via NPX:

• The pnpm package manager. Installation guide
• Node.js version 18.0.0 or higher.

For setup via Docker:

• A functional Docker runtime environment. Docker setup guide

Deployment Instructions

Integration with Cursor IDE

Local Execution via NPX

In your Cursor MCP configuration file, incorporate the following block:

{ "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" // Applicable only for self-hosted deployments } } } }

Local Execution via Docker

Adjust your Cursor MCP configuration as follows:

{ "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 for on-prem } } } }

Utilizing a Remotely Hosted MCP Server

Configure your Cursor MCP settings like this:

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

Integration with VS Code

Local Execution via NPX (in .vscode/mcp.json)

{ // Inputs prompt on initial startup, then persisted by VS Code. "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": { // Reference: https://github.com/ppl-ai/modelcontextprotocol/ "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}" } } } }

Local Execution via Docker (in .vscode/mcp.json)

{ // Inputs prompt on initial startup, then persisted by VS Code. "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": { // Reference: https://github.com/ppl-ai/modelcontextprotocol/ "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}" } } } }

Utilizing a Remotely Hosted MCP Server (in .vscode/mcp.json)

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

Integration with Claude Desktop

Local Execution via NPX (in 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" // Optional for on-prem } } } }

Configuration File Locations: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Claude Desktop Setup Guide

Local Execution via Docker (in claude_desktop_config.json)

{ "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 for on-prem } } } }

To locate/create the config file: Navigate to Claude Desktop Settings -> Developer -> Edit Config.

Utilizing a Remotely Hosted MCP Server (Claude Desktop)

Step 1: Create a wrapper script (e.g., circleci-remote-mcp.sh):

bash

!/bin/bash

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

Step 2: Ensure executability:

bash chmod +x circleci-remote-mcp.sh

Step 3: Update claude_desktop_config.json:

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

Integration with Claude Code

Use the CLI to register servers:

Local Execution via NPX:

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

Local Execution via Docker:

bash 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

Utilizing a Remotely Hosted MCP Server:

bash 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

Claude Code MCP Guide

Integration with Windsurf

Local Execution via NPX (in 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" // Optional for on-prem } } } }

Local Execution via Docker (in mcp_config.json)

{ "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 for on-prem } } } }

Utilizing a Remotely Hosted MCP Server (Windsurf)

In your windsurf mcp_config.json:

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

Windsurf MCP Documentation

Automated Installation via Smithery

For automatic setup in Claude Desktop via Smithery:

bash npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude

Amazon Q Developer CLI Configuration

MCP settings reside in mcp.json, either globally (~/.aws/amazonq/mcp.json) or locally (.amazonq/mcp.json in the workspace). Workspace settings override global ones.

Local Execution via NPX (Amazon Q)

In the relevant mcp.json file:

{ "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 for on-prem }, "timeout": 60000 } } }

Utilizing a Remotely Hosted MCP Server (Amazon Q CLI)

Step 1: Create wrapper script (e.g., circleci-remote-mcp.sh):

bash

!/bin/bash

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

Step 2: Make executable:

bash chmod +x circleci-remote-mcp.sh

Step 3: Register via Q CLI:

bash q mcp add --name circleci --command "/full/path/to/circleci-remote-mcp.sh"

Amazon Q Developer in IDE Configuration

Local Execution via NPX (Amazon Q IDE)

Use the relevant mcp.json file (global or local workspace) with this content:

{ "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 for on-prem }, "timeout": 60000 } } }

Utilizing a Remotely Hosted MCP Server (Amazon Q IDE)

Step 1: Create wrapper script (e.g., circleci-remote-mcp.sh):

bash

!/bin/bash

npx mcp-remote http://your-circleci-remote-mcp-server-endpoint:8000/mcp --allow-http

Step 2: Make executable:

bash chmod +x circleci-remote-mcp.sh

Step 3: Configure via IDE UI (Access Guide):

1. Open the MCP configuration interface.
2. Click the Add (+) icon.
3. Specify Scope (global or local project).
4. Set Name (e.g., circleci-remote-mcp).
5. Set Transport Protocol to stdio.
6. Provide the absolute path to your script in the Command field (e.g., /full/path/to/circleci-remote-mcp.sh).
7. Save the configuration.

Capabilities Summary

Available Interaction Tools

• get_build_failure_logs: Fetches exhaustive failure diagnostics from CircleCI executions. Contextual invocation methods include:

  1. Project Slug & Branch: (Requires prior project listing via list_followed_projects to obtain projectSlug). E.g., "Retrieve build failure reports for my-project on the development branch".
  2. Direct CircleCI URL: Supply a specific job, workflow, or pipeline URL. E.g., "Extract logs from https://app.circleci.com/pipelines/github/org/repo/123".
  3. Local Repository Context: Uses current workspace path, remote Git URL, and active branch. E.g., "Show me the diagnostic output for the latest pipeline failure on my active branch".

  Output includes structured job timelines, granular execution feedback, and clear error diagnostics, aiding rapid debugging within the IDE.

• find_flaky_tests: Scans execution history to pinpoint tests exhibiting inconsistent behavior, leveraging CircleCI's test insights feature. Input methods:

  1. Project Slug: After selecting a project (e.g., "Show flaky tests for my-project").
  2. Project URL: E.g., "Analyze flakiness in https://app.circleci.com/pipelines/github/org/repo".
  3. Local Context: E.g., "Identify unreliable tests in this repository".

  Results are provided as text output by default, or optionally written to a directory specified by the FILE_OUTPUT_DIRECTORY environment variable, detailing test identifiers and failure contexts.

• get_latest_pipeline_status: Reports the current state of the most recent pipeline run for a specified context.

  1. Project Slug & Branch: E.g., "What is the status of the deployment pipeline for my-project on 'release/v2' branch?".
  2. Project URL: E.g., "Check pipeline status for https://app.circleci.com/pipelines/github/org/repo".
  3. Local Context: E.g., "Report status for the pipeline associated with my current repository checkout".

  Returns a structured summary including workflow names, success/failure status, duration metrics, and precise timestamp markers.

• get_job_test_results: Extracts comprehensive test metadata from CircleCI jobs.

  1. Project Slug & Branch: E.g., "Fetch test outcome summaries for my-project on the staging branch".
  2. Specific CircleCI URL: Accepts Job, Workflow, or Pipeline URLs. E.g., "Analyze tests from job URL: [URL]".
  3. Local Context: E.g., "Provide a breakdown of test runs for the current branch".

  This tool details total counts, lists failures with stack traces and timing, and enumerates successful tests, minimizing the need to navigate the web UI. (Requires test metadata collection configuration per CircleCI documentation).

• config_helper: Assists in maintaining the integrity of CircleCI configuration files (e.g., .circleci/config.yml).

  1. Validation: Checks syntax and semantic correctness. E.g., "Audit my CircleCI configuration file for errors".

  Provides actionable feedback, recommendations, and flags pre-commit configuration defects.

• create_prompt_template: Utility for transforming user feature requests into formalized, structured prompt definitions suitable for AI augmentation.

  1. Generation: Converts abstract needs into concrete templates. E.g., "Draft a structured prompt definition for categorizing incoming support tickets by severity and component".

  Yields a complete prompt template alongside a required context schema.

• recommend_prompt_template_tests: Develops a comprehensive set of verification scenarios to validate the robustness and accuracy of generated AI prompt templates.

  1. Test Case Generation: Creates diverse inputs based on the template and its schema. E.g., "Generate validation tests for the support ticket categorization prompt".

  Returns an array of test payloads designed to confirm expected AI behavior and expose edge cases.

• list_followed_projects: Fetches the inventory of accessible CircleCI projects.

  1. Retrieval: Displays projects and their critical identifiers. E.g., "Display all CircleCI projects I can access".

  Output format includes the user-friendly name and the essential projectSlug (e.g., gh/organization/my-project), which is necessary input for most other CircleCI tools.

• run_pipeline: Initiates the execution of a CircleCI pipeline.

  1. Project Slug & Branch: E.g., "Start a build process for my-project on the hotfix branch".
  2. Specific CircleCI URL: Targets a pipeline via URL. E.g., "Trigger the pipeline associated with this workflow URL: [URL]".
  3. Local Context: E.g., "Execute the pipeline for my current repository state on the main branch".

  Returns a direct monitoring link for the newly launched execution.

• run_rollback_pipeline: Orchestrates project rollbacks. This complex operation involves several prerequisite steps that the tool attempts to resolve automatically:

  1. Project identification (using list_followed_projects).
  2. Environment identification.
  3. Component identification.
  4. Version selection (from list_component_versions).

  It then determines whether to trigger a full rollback pipeline or rerun a specific prior workflow, concludes with a confirmation prompt, and executes the selected rollback method.

• rerun_workflow: Restarts a CircleCI workflow, optionally resuming from the point of the last failure.

  Returns the identifier and monitoring link for the newly instantiated workflow run.

• analyze_diff: Audits local code changes (git diff) against established quality rules defined locally (e.g., .cursorrules).

  1. Diff Source: Input can be staged (git diff --cached), unstaged (git diff), or against HEAD.
  2. Rule Source: Uses local rule files.

  Provides granular reports detailing rule non-compliance, supporting proactive quality enforcement before merging.

• list_component_versions: Queries historical versions for a specific software component deployed within a CircleCI environment. The tool interactively prompts for component and environment if necessary, returning detailed metadata including deployment status (is_live), associated pipeline/workflow IDs, and deployment timestamps.

• download_usage_api_data: Exports organizational consumption metrics from the CircleCI Usage API. (Cloud installations only). Accepts flexible natural language date inputs (e.g., "last week"). 1) New Export: Requires orgId, date range (startDate, endDate - max 32 days span), and outputDir. 2) Job Status/Download: Requires orgId, jobId, and outputDir.

  The result is a CSV file containing usage details, which can then feed into cost optimization tools.

• find_underused_resource_classes: Processes a usage CSV (obtained via download_usage_api_data) to pinpoint compute resources (CPU/RAM) where average utilization falls below a configurable percentage (default 40%).

  Generates a markdown summary listing specific jobs/workflows exhibiting low utilization, facilitating compute resource optimization efforts.

Debugging and Maintenance

Remediation Strategies

Frequent Failures Checklist:

1. Cache Clearing: Execute package manager cache resets: bash npx clear-npx-cache npm cache clean --force

2. Version Pinning: Ensure the latest tag is referenced in configuration:

   "args": ["-y", "@circleci/mcp-server-circleci@latest"]

3. Application Restart: Perform a full restart of the host IDE environment (not merely a window reload).

Authorization Concerns

• Token Errors: Revalidate the CIRCLECI_TOKEN against Personal API Tokens.
• Access Rights: Verify the token possesses necessary read permissions for target projects.
• Env Variable Integrity: Confirm environment variables propagate correctly using shell checks (echo $CIRCLECI_TOKEN).

Connectivity and Network Diagnostics

• Base URL Check: Confirm CIRCLECI_BASE_URL is set to https://circleci.com.
• Proxy Configuration: If operating within a corporate firewall, ensure npm proxy settings are correctly established.
• Security Software: Temporarily disable local firewalls/security tools to rule out download interference.

Runtime Environment Validation

• Node Check: Verify version integrity: node --version (must be >= 18.0.0).
• Package Manager Status: Confirm functionality: npm --version.

Advanced Diagnostics

• Direct Execution Test: Run the server executable with help flag: npx @circleci/mcp-server-circleci@latest --help
• Verbose Tracing: Enable deep logging: DEBUG=* npx @circleci/mcp-server-circleci@latest
• Docker Fallback: If NPX installations yield persistent problems, switch to Docker deployment.

Support Pathway

1. Search existing GitHub issues for matching symptoms.
2. When reporting, include OS details, Node version, IDE name, and any relevant console error output.

Development Workflow

Initial Setup

1. Clone the repository source code:

   bash git clone https://github.com/CircleCI-Public/mcp-server-circleci.git cd mcp-server-circleci

2. Install project dependencies:

   bash pnpm install

3. Compile the project assets: bash pnpm build

Container Image Construction

Build the Docker image locally using:

bash docker build -t circleci:mcp-server-circleci .

To test the image locally:

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

To initiate the image as a remote server instance, append the start=remote and optionally a custom port=<number> environment variable:

bash docker run --rm -i -e CIRCLECI_TOKEN=your-ci-token -e CIRCLECI_BASE_URL=https://circleci.com circleci:mcp-server-circleci -e start=remote -e port=8000

Iterative Development with MCP Inspector

Use the inspector for rapid cycle development:

1. Server Watch Mode: Maintain a running build process:

   bash pnpm watch

2. Inspector Launch: Open the debugging interface in a separate terminal:

   bash pnpm inspector

3. Environment Configuration: In the inspector UI, configure the CIRCLECI_TOKEN (requires read permissions) and optionally the CIRCLECI_BASE_URL (defaults correctly).

Testing Suite

• Execute all automated tests:

  bash pnpm test

• Activate continuous testing during development:

  bash pnpm test:watch

Refer to CONTRIBUTING.md for comprehensive guidelines on contribution standards.