Empowering LLMs with CircleCI Context: An MCP Server Solution

Harness the power of Large Language Models (LLMs) within your CircleCI workflows using the Model Context Protocol (MCP). This repository provides an MCP Server, enabling seamless integration between LLMs and CircleCI, allowing you to leverage natural language for tasks like retrieving logs and identifying flaky tests.

Key Features and Benefits

• LLM-Powered CircleCI Interaction: Use natural language commands within your IDE or other MCP-compatible clients to interact with CircleCI.
• Enhanced Debugging: Quickly retrieve detailed failure logs from CircleCI builds using natural language queries.
• Flaky Test Detection: Identify and analyze flaky tests in your CircleCI projects, improving test suite reliability.
• Seamless Integration: Easily integrate with popular IDEs like Cursor, VS Code, and Claude Desktop, as well as tools like Windsurf.
• Standardized Protocol: Built on the Model Context Protocol (MCP), ensuring compatibility and future-proof integration.

Getting Started

Prerequisites

• pnpm: A fast and efficient package manager. Install it here.
• Node.js: Version 18.0.0 or higher.
• CircleCI API Token: Generate a personal API token with read access from your CircleCI account here. Refer to the official documentation for more details.

Installation and Configuration

The CircleCI MCP Server can be integrated with various MCP clients. Below are instructions for some popular options:

Cursor IDE

1. Open your Cursor IDE settings.

2. Locate the MCP configuration.

3. Add the following configuration block:

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

   Replace "your-circleci-token" with your actual CircleCI API token. For on-premise CircleCI installations, configure the CIRCLECI_BASE_URL accordingly.

4. Refer to the Cursor documentation for further details.

Claude Desktop

1. Open Claude Desktop settings.

2. Navigate to "Developer" in the left-hand bar.

3. Click "Edit Config" to open or create the claude_desktop_config.json file. The file is typically located at:

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

4. Add the following configuration block:

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

   Replace "your-circleci-token" with your actual CircleCI API token. For on-premise CircleCI installations, configure the CIRCLECI_BASE_URL accordingly.

VS Code

1. Open your VS Code settings (settings.json).

2. Add the following configuration block under the mcp -> servers section:

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

   Replace "your-circleci-token" with your actual CircleCI API token. For on-premise CircleCI installations, configure the CIRCLECI_BASE_URL accordingly.

3. Refer to the VS Code documentation for further details.

Windsurf

1. Locate your Windsurf mcp_config.json file.

2. Add the following configuration block:

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

   Replace "your-circleci-token" with your actual CircleCI API token. For on-premise CircleCI installations, configure the CIRCLECI_BASE_URL accordingly.

3. Refer to the Windsurf documentation for further details.

Available Tools

The CircleCI MCP Server provides the following tools:

get_build_failure_logs

This tool retrieves detailed failure logs from CircleCI builds, enabling faster debugging and issue resolution.

• Usage:

  1. Using CircleCI URLs: Provide a direct link to a failed job or pipeline.

     • Example: "Get logs from https://app.circleci.com/pipelines/github/org/repo/123"

  2. Using Local Project Context: Execute the command from your local workspace, providing the workspace root path, Git remote URL, and branch name.

     • Example: "Find the latest failed pipeline on my current branch"

• Output: The tool returns formatted logs, including job names, step-by-step execution details, and failure messages.

find_flaky_tests

This tool identifies flaky tests in your CircleCI project by analyzing test execution history, leveraging CircleCI's flaky test detection feature.

• Usage:

  1. Using CircleCI Project URL: Provide the project URL directly from CircleCI.

     • Example: "Find flaky tests in https://app.circleci.com/pipelines/github/org/repo"

  2. Using Local Project Context: Execute the command from your local workspace, providing the workspace root path and Git remote URL.

     • Example: "Find flaky tests in my current project"

• Output: The tool returns detailed information about flaky tests, including test names, file locations, and failure messages.

Development

Local Development Setup

1. Clone the repository:

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

2. Install dependencies:

   pnpm install

3. Build the project:

   pnpm build

Development with MCP Inspector

The MCP Inspector provides an interactive environment for developing and testing MCP Servers.

1. Start the development server:

   pnpm watch # Keep this running in one terminal

2. Launch the inspector:

   pnpm inspector

3. Configure the environment:

   • Add your CIRCLECI_TOKEN to the Environment Variables section in the inspector UI.
   • Ensure the token has read access to your CircleCI projects.
   • Optionally, set your CircleCI Base URL. It defaults to https://circleci.com.

Testing

• Run the test suite:

  pnpm test

• Run tests in watch mode:

  pnpm test:watch

For detailed contribution guidelines, refer to CONTRIBUTING.md.