CircleCI MCP Server

• Find the latest failed pipeline on my branch and get logs

  https://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide

Requirements

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

Installation

Installing via Smithery

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

Cursor

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

Claude Desktop

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

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

Claude Code

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

VS Code

mcp -> servers

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

Windsurf

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

Features

Supported Tools

• get_build_failure_logs

  Retrieves detailed failure logs from CircleCI builds. This tool can be used in two ways:
  1. Using CircleCI URLs:
     • Provide a failed job URL or pipeline URL directly
     • Example: "Get logs from https://app.circleci.com/pipelines/github/org/repo/123"
  2. Using Local Project Context:
     • Works from your local workspace by providing:
       • Workspace root path
       • Git remote URL
       • Branch name
     • Example: "Find the latest failed pipeline on my current branch"
  The tool returns formatted logs including:
  • Job names
  • Step-by-step execution details
  • Failure messages and context
  This is particularly useful for:
  • Debugging failed builds
  • Analyzing test failures
  • Investigating deployment issues
  • Quick access to build logs without leaving your IDE

• find_flaky_tests

  Identifies flaky tests in your CircleCI project by analyzing test execution history. This leverages the flaky test detection feature described here: https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detection
  This tool can be used in two ways:
  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:
     • Works from your local workspace by providing:
       • Workspace root path
       • Git remote URL
     • Example: "Find flaky tests in my current project"
  The tool returns detailed information about flaky tests, including:
  • Test names and file locations
  • Failure messages and contexts
  This helps you:
  • Identify unreliable tests in your test suite
  • Get detailed context about test failures
  • Make data-driven decisions about test improvements

• config_helper

  Assists with CircleCI configuration tasks by providing guidance and validation. This tool helps you:
  1. Validate CircleCI Config:
     • Checks your .circleci/config.yml for syntax and semantic errors
     • Example: "Validate my CircleCI config"
  The tool provides:
  • Detailed validation results
  • Configuration recommendations
  This helps you:
  • Catch configuration errors before pushing
  • Learn CircleCI configuration best practices
  • Troubleshoot configuration issues
  • Implement CircleCI features correctly

Development

Getting Started

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

1. Start the development server:

   pnpm watch # Keep this running in one terminal
   

2. In a separate terminal, launch the inspector:

   pnpm inspector
   

3. Configure the environment:
   • Add your

     CIRCLECI_TOKEN

     to the Environment Variables section in the inspector UI
   • The token needs read access to your CircleCI projects
   • Optionally you can set your CircleCI Base URL. Defaults to

     https//circleci.com

Testing

• Run the test suite:

  pnpm test
  

• Run tests in watch mode during development:

  pnpm test:watch