Circleci MCP Server

🚀 CircleCI Server

CircleCI Server is a tool built on MCP (Machine Learning Configuration Protocol), aiming to provide developers with convenient support for CircleCI-related functions. Currently, the server mainly offers the following tools:

🚀 Quick Start

✨ Features

• Get Build Failure Logs: Retrieve build failure log information from CircleCI, supporting direct access via URL or use in the local project environment.
• Find Flaky Tests: Analyze historical test execution data in CircleCI projects to identify flaky test cases and provide detailed information.
• Configuration Assistant: Validate and guide the writing of CircleCI configuration files, helping developers avoid configuration errors and improve configuration efficiency.

📦 Installation

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

💻 Usage Examples

Development Guide

1. Start the development server:

pnpm watch # Keep running in the terminal

2. Debug using MCP Inspector Start the Inspector in another terminal:

pnpm inspector

• Add CIRCLECI_TOKEN to the environment variables to ensure the token has permission to access the CircleCI project.
• Optional: Configure the CircleCI base URL, default is https://circleci.com

Testing Guide

1. Run the test suite:

pnpm test

2. Real-time testing in development mode:

pnpm test:watch

For more detailed contribution guidelines, please refer to CONTRIBUTING.md

📚 Documentation

Get Build Failure Logs

This tool supports the following two usage methods:

1. Directly obtain via CircleCI URL Example: "Get the build logs of https://app.circleci.com/pipelines/github/org/repo/123"

2. Use in the local project environment Just provide the workspace root path, Git remote URL, and branch name.

The returned log information includes:

• Job name
• Execution step details
• Failure message and context

Find Flaky Tests

By analyzing the test execution history data of CircleCI projects, identify flaky test cases and provide detailed information. It supports the following two methods:

1. Directly obtain via the project URL Example: "Find flaky tests in https://app.circleci.com/pipelines/github/org/repo"

2. Use in the local project environment Just provide the workspace root path and Git remote URL.

The returned detailed information includes:

• Test name and file location
• Failure message and context

Configuration Assistant

1. Validate the CircleCI configuration file Check if the .circleci/config.yml file has syntax or semantic errors. Example: "Validate my CircleCI configuration"

The returned information includes:

• Detailed validation results
• Configuration suggestions