CircleCI MCP Server Project Introduction

Project Overview

The CircleCI MCP Server is a professional server implementation designed specifically for the Model Context Protocol (MCP), aimed at integrating with CircleCI's development workflows. This project serves as a bridge between CircleCI infrastructure and the Model Context Protocol, providing an enhanced AI-driven development experience.

This server enables AI tools like Cursor, Claude Code, Windsurf, etc., to understand your build system. It is built on the Model Context Protocol (MCP), a lightweight standard that allows LLM-driven agents to fetch structured data from external systems.

Core Features

Main Tools and Functions

1. get_build_failure_logs

Retrieves detailed failure logs for CircleCI builds. This tool supports two usage methods:

Using CircleCI URL:

Directly provide the URL of the failed job or pipeline.
Example: "Get logs for https://app.circleci.com/pipelines/github/org/repo/123"

Using Local Project Context:

Work from your local workspace by providing the following information:
- Workspace root path
- Git remote URL
- Branch name
Example: "Find the latest failed pipeline on my current branch"

The returned formatted logs include:

Job name
Step-by-step execution details
Failure messages and context

2. find_flaky_tests

Identifies flaky tests in a CircleCI project by analyzing test execution history. Supports two usage methods:

Using CircleCI Project URL:

Directly provide the project URL from CircleCI.
Example: "Find flaky tests in https://app.circleci.com/pipelines/github/org/repo"

Using Local Project Context:

Work from your local workspace by providing the workspace root path and Git remote URL.

Returns detailed information about flaky tests, including:

Test name and file location
Failure messages and context

3. get_latest_pipeline_status

Retrieves the status of the latest pipeline for a given branch. The tool returns a formatted status of the latest pipeline:

Workflow name and its current status
Duration of each workflow
Creation and completion timestamps
Overall pipeline health

Example output:

--- 
Workflow: build 
Status: success 
Duration: 5 minutes 
Created: 4/20/2025, 10:15:30 AM 
Stopped: 4/20/2025, 10:20:45 AM 
--- 
Workflow: test 
Status: running 
Duration: unknown 
Created: 4/20/2025, 10:21:00 AM 
Stopped: in progress

4. get_job_test_results

Retrieves test metadata for a CircleCI job, allowing you to analyze test results without leaving your IDE.

Returns detailed test result information:

Summary of all tests (total, success, failure)
Details of failed tests, including:
- Test name and class
- File location
- Error message
- Runtime duration
List of successful tests with timing information

5. config_helper

Assists with CircleCI configuration tasks, providing guidance and validation. This tool helps you:

Validate CircleCI configuration:
- Check your .circleci/config.yml for syntax and semantic errors.
- Example: "Validate my CircleCI configuration"

Provides:

Detailed validation results
Configuration suggestions

6. create_prompt_template

Generates structured prompt templates for AI-enabled applications based on functional requirements. This tool:

Transforms functional requirements into structured prompts:
- Converts user needs into optimized prompt templates.
- Example: "Create a prompt template for generating bedtime stories by age and theme"

7. recommend_prompt_template_tests

Generates test cases for prompt templates, ensuring they produce expected results.

Installation and Configuration

System Requirements

pnpm package manager - Learn more
Node.js >= v18.0.0
CircleCI API Token - You can generate one through CircleCI. Learn more or click here for quick access.

Supported IDEs and Tools

Cursor IDE

Add the following to your Cursor MCP configuration:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - only needed for on-premise customers
      }
    }
  }
}

VS Code

Install the CircleCI MCP server in .vscode/mcp.json:

{
  // 💡 Input is prompted on first server start, then securely stored by VS Code
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}"
      }
    }
  }
}

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - only needed for on-premise customers
      }
    }
  }
}

Configuration file location:

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

Claude Code

After installing Claude Code, run the following command:

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

Windsurf

Add the following to your windsurf mcp_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - only needed for on-premise customers
      }
    }
  }
}

Automatic Installation

Automatically install the CircleCI MCP server for Claude Desktop via Smithery:

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

Development and Contribution

Local Development Setup

Clone the repository:

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

Install dependencies:

pnpm install

Build the project:

pnpm build

Developing with the MCP Inspector

The easiest way to iterate on the MCP server is with the MCP Inspector.

Start the development server:

pnpm watch # Keep running in one terminal

Start the inspector in a separate terminal:

pnpm inspector

Configure the environment:
- Add your CIRCLECI_TOKEN in the environment variables section of the inspector UI.
- The token needs read access to your CircleCI projects.
- Optionally set your CircleCI base URL, which defaults to https://circleci.com.

Testing

Run the test suite:

pnpm test

Run tests in watch mode during development:

pnpm test:watch

Use Cases

This tool is particularly useful for:

Debugging failed builds
Analyzing test failures
Investigating deployment issues
Quickly accessing build logs without leaving the IDE
Checking the status of the latest pipeline
Identifying unreliable tests in the test suite
Making data-driven decisions about test improvements

Project Advantages

The CircleCI MCP Server is designed to support the real moments in the development lifecycle. Whether you're reviewing a failed build, debugging a failed deployment, or keeping an eye on a critical branch, it helps your assistant understand the failure and suggest fixes in seconds—without context switching.

By integrating this MCP server, developers can:

Interact with CircleCI using natural language
Obtain build information within their familiar development environment
Quickly diagnose and resolve CI/CD issues
Improve the efficiency of their development workflows

Related Resources

For more detailed contribution guidelines, please refer to the CONTRIBUTING.md file in the project.