Circleci Public MCP Server Circleci

🚀 CircleCI MCP Server

The Model Context Protocol (MCP) is a new standard protocol for managing context between Large Language Models (LLMs) and external systems. In this repository, we provide an MCP server for CircleCI.

This allows you to use the Cursor IDE or any MCP client to interact with CircleCI through natural language, such as:

• Find the latest failed pipeline on my branch and get the logs https://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide

https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74

🚀 Quick Start

The Model Context Protocol (MCP) is a new standard protocol for managing context between Large Language Models (LLMs) and external systems. This MCP server for CircleCI enables interaction with CircleCI via natural - language commands in Cursor IDE or other MCP clients.

📦 Installation

Prerequisites

• pnpm package manager - Learn more
• Node.js >= v18.0.0
• CircleCI API token - You can generate one through CircleCI. Learn more or Quick access here

Cursor

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

See more guides on configuring the MCP server with Cursor: https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers

✨ Features

Supported Tools

• get_build_failure_logs

  Retrieve detailed failure logs from CircleCI builds. This tool can be used in two ways:

  1. Using a CircleCI URL:

     • Provide a failed job URL or pipeline URL.
     • Example: Get the logs for https://app.circleci.com/pipelines/github/org/repo/123

  2. Using local project context:

     • Use the following information in your local workspace:
       • 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 name
  • Details of executed steps
  • Failure messages and context

  This is useful for:

  • Debugging build failures
  • Analyzing test failures
  • Investigating deployment issues
  • Quickly accessing build logs without leaving the IDE

🔧 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

The easiest way to iterate on the MCP server is by using the MCP inspector. You can learn more about the MCP inspector here

1. Start the development server:

   pnpm watch # Keep this terminal running
   

2. Start the inspector in another terminal:

   pnpm inspector
   

3. Configure the environment:

   • Add your CIRCLECI_TOKEN to the environment variables section.
   • The token needs read access to the CircleCI project.
   • Optionally, set your CircleCI Base URL. The default is https://circleci.com

Contribution

See more contribution guidelines: CONTRIBUTING.md