CircleCI MCP Server

GitHub

CircleCI

npm

Model Context Protocol (MCP) is a new, standardized protocol for managing context between large language models (LLMs) and external systems. In this repository, we provide an MCP Server for CircleCI.

This lets you use Cursor IDE, or any MCP Client, to use natural language to accomplish things with CircleCI, e.g.:

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

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

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

Cursor

Add the following to your cursor MCP config:

{
  "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 the guide below for more information on using MCP servers with cursor: https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers

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

Development

Getting Started

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
```

Development with MCP Inspector

The easiest way to iterate on the MCP Server is using the MCP inspector. You can learn more about the MCP inspector at https://modelcontextprotocol.io/docs/tools/inspector

Start the development server:

pnpm watch # Keep this running in one terminal

In a separate terminal, launch the inspector:
```
pnpm inspector
```
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
```

For more detailed contribution guidelines, see CONTRIBUTING.md