Home
Login
CircleCI-Public/mcp-server-circleciPlease refer to the latest official releases for information GitHub Homepage

CircleCI MCP Server - A professional server implementation designed specifically for the Model Context Protocol, used for integrating CircleCI development workflows.

Apache-2.0TypeScript 50CircleCI-Publicmcp-server-circleci Last Updated: 2025-06-23

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:

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:

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

  1. Clone the repository:
git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci
  1. Install dependencies:
pnpm install
  1. Build the project:
pnpm build

Developing with the MCP Inspector

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

  1. Start the development server:
pnpm watch # Keep running in one terminal
  1. Start the inspector in a separate terminal:
pnpm inspector
  1. 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.

Star History Chart