CircleCI MCP Conduit

This repository delivers an MCP Server implementation specifically tailored for interaction with the CircleCI continuous integration platform. Model Context Protocol (MCP) establishes a universal standard for LLM-external system communication. Using this server, developers can leverage conversational AI within MCP-compatible clients (such as Cursor, Copilot, Windsurf, or others) to automate complex CI/CD tasks.

For instance, you can issue directives like:

• Fetch the run logs for the most recent pipeline failure on my current feature branch Integration Guide for Cursor

Prerequisites

To initialize the service, you must possess a valid CircleCI Personal API Token. This token grants necessary permissions for API interaction. Obtainable via the CircleCI console: Token Management.

For NPX Deployment:

• pnpm package manager (recommended: Installation Guide)
• Node.js runtime, minimum version 18.0.0 or newer

For Docker Deployment:

• Docker Engine installed and operational

Deployment Methods

Client Configuration Examples

Configuration snippets for integrating this server into various client applications are detailed below. Note: Always substitute placeholders like your-circleci-token with your actual credentials or secure input references.

Integration within Cursor IDE

Local Execution via NPX: Update your Cursor configuration file:

{ "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" // Omit or adapt for self-hosted instances } } } }

Local Execution via Docker: Modify your Cursor configuration:

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

Remote Endpoint Configuration: For connecting to a pre-existing 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" } } }

Integration within VS Code (via .vscode/mcp.json)

Local NPX Setup:

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

Integration within Claude Desktop

Configuration resides in claude_desktop_config.json (locations: ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows).

Self-Managed Remote Server Script Wrapper (Example for Claude Desktop):

Create 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

Make executable (chmod +x circleci-remote-mcp.sh) and configure Claude Desktop:

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

Integration within Claude Code (CLI)

Use the claude mcp add command for easy setup:

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

Integration within Windsurf

In windsurf mcp_config.json:

Remote Server Configuration:

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

Automated Installation via Smithery

To deploy this server automatically for Claude Desktop clients:

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

Amazon Q Developer Configuration

Amazon Q manages MCP settings in mcp.json (either globally at ~/.aws/amazonq/mcp.json or workspace-local at .amazonq/mcp.json).

Local NPX Setup for Q Developer 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" }, "timeout": 60000 } } }

Available Capabilities

This conduit exposes several specific functions for interacting with CircleCI artifacts and workflows:

• get_build_failure_logs

Fetches comprehensive diagnostic logs pertaining to build failures. Contextual retrieval methods include: 1. Project Slug & Branch: Requires prior discovery via list_followed_projects. Example: "Show me the errors from the failing job on 'my-project' branch 'develop'." 2. Direct URL: Supplying a direct link to a pipeline or job. Example: "Extract logs from pipeline run ID 12345." 3. Local Context: Utilizing current workspace details (path, remote URL, branch). Example: "Debug the last build failure on this repository's active branch."

Output details include step-by-step execution records, failure summaries, and relevant context data, vital for rapid debugging.

• find_flaky_tests

Leverages CircleCI's built-in Test Insights to pinpoint non-deterministic tests. Referencing the feature documentation: Flaky Test Detection.

Usage scenarios involve specifying the project (via slug or URL) or relying on local repository context.

Output can be text-based (default) or file-based (if FILE_OUTPUT_DIRECTORY is set), providing test names, locations, and error context.

• get_latest_pipeline_status

Returns the execution state of the most recent workflow run for a specified branch or project URL.

The result is structured, detailing each workflow's status (success, failure, running), temporal data (timestamps), and duration.

• get_job_test_results

Retrieves granular metadata from job test artifacts. This bypasses the need to navigate the web interface for test analysis.

It synthesizes summaries of passed/failed tests, including timings and specific failure messages/locations. Crucial for diagnosing intermittent failures or slow tests.

• config_helper

A utility for validating and providing suggestions on .circleci/config.yml files. Example: "Check this configuration file for syntax errors."

• create_prompt_template / recommend_prompt_template_tests

Utilities for engineering high-quality, structured prompt definitions for AI systems, including generating corresponding test suites.

• list_followed_projects

Fetches and lists all projects accessible to the authenticated user, critically providing the projectSlug required by most other CircleCI tools. Example: "Show me all CI projects I can access."

• run_pipeline

Initiates a new pipeline execution on a designated branch or via a context URL. Returns a monitor link for tracking. Example: "Start a build for the 'staging' branch of 'my-app-project'."

• run_rollback_pipeline

Orchestrates environment rollbacks, capable of triggering a formal rollback pipeline or rerunning a prior successful workflow, based on project configuration. This tool guides the user through selecting the project, environment, component, and target version.

• rerun_workflow

Restarts a workflow, optionally starting from the job where it previously encountered a failure. Returns the identifier and tracking URL for the new run.

• analyze_diff

Applies specified repository rules (from .cursorrules or similar) against provided Git diff content (staged/unstaged) to flag immediate quality violations before submission.

• list_component_versions

Queries version history for components within specific environments, detailing deployment status, pipeline IDs, and timestamps. Essential for auditing deployments or selecting rollback targets.

• download_usage_api_data

Fetches operational metrics from the CircleCI Usage API for an organization over a specified, short date range (max 32 days), outputting the data as a CSV file.

• find_underused_resource_classes

Processes the usage CSV (obtained via download_usage_api_data) to identify CI jobs consuming significantly less computational power (CPU/RAM) than allocated by their configured resource class, signaling potential cost savings.

Maintenance and Debugging

Rapid Remediation Steps

If initialization fails, try these initial actions: 1. Purge Package Cache: Execute npx clear-npx-cache followed by npm cache clean --force. 2. Pin Version: Explicitly use @latest in configuration arguments. 3. Full IDE Restart: Completely close and relaunch your development environment.

Authorization Challenges

• Token Validity: Reconfirm the CIRCLECI_TOKEN is correct in your Personal API Tokens section.
• Scope: Ensure the token has the requisite permissions (read access).

Development Workflow

To iterate locally, use the following sequence:

1. Clone and navigate to the repository.
2. Install dependencies: pnpm install
3. Start the watching build process: pnpm watch
4. Use the MCP Inspector (run via pnpm inspector) to connect and test server interactions live, configuring your API token within the inspector UI.

Contextual Background

Cloud Computing Definition (ISO/NIST Framework): Cloud computing represents a consumption model for scalable, elastic, on-demand IT infrastructure accessible via the network. NIST defines five core attributes: self-service provisioning, broad network availability, resource pooling, rapid elasticity, and metered usage, forming the bedrock of modern infrastructure delivery.