Use CircleCI with Natural Language: A Guide to CircleCI MCP Server

Imagine using plain English to interact with CircleCI! The CircleCI MCP (Model Context Protocol) Server makes it a reality. This article walks you through using natural language to retrieve logs, find flaky tests, and manage your pipelines directly from your favorite IDEs. Let's dive in!

What is the CircleCI MCP Server?

The CircleCI MCP Server is a bridge between Large Language Models (LLMs) and CircleCI. It utilizes the Model Context Protocol (MCP) to help you manage your CI/CD workflows using natural language commands. Think of it as your personal CircleCI assistant controlled by your voice or typed commands.

Why Use CircleCI with Natural Language?

• Boost Productivity: Stop clicking through dashboards. Get key information with simple commands.
• Simplify Debugging: Quickly retrieve logs and identify problematic tests via natural language prompts.
• Seamless Integration: Works directly within your IDE (Cursor, VS Code) and other compatible tools like Claude & Windsurf.
• Improved Workflow: Focus on coding, not navigating complex CI/CD systems.

CircleCI MCP Server Requirements

Before you begin, make sure you have the following:

• pnpm: A fast and efficient package manager (learn more).
• Node.js: Version 18.0.0 or higher.
• CircleCI API Token: Generate one through your CircleCI account with read access (get your token).

Installation Guides for Popular IDEs

Here's how to set up the CircleCI MCP Server in different IDEs and platforms.

Cursor IDE Configuration

1. Add the following to your Cursor MCP configuration file:

{
 "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 - for on-prem users
 }
 }
 }
}

1. Remember to replace "your-circleci-token" with your actual CircleCI API token.
2. For detailed instructions, refer to the Cursor MCP documentation.

VS Code Configuration

1. In your .vscode/mcp.json file, add the following:

{
 "inputs": [
 {
 "type": " promptString ",
 "id": " circleci-token ",
 "description": " CircleCI API Token ",
 "password": true
 }
 ],
 "servers": {
 "circleci-mcp-server": {
 "type": " stdio ",
 "command": " npx ",
 "args": [ " -y ", " @circleci/mcp-server-circleci "],
 "env": {
 "CIRCLECI_TOKEN": " ${input:circleci-token} "
 }
 }
 }
}

1. VS Code will prompt you for your CircleCI API token the first time you run the server.
2. Consult the VS Code documentation for more information on MCP servers.

Claude Desktop Setup

1. Add the following configuration to your claude_desktop_config.json file:

{
 "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 - for on-prem users
 }
 }
 }
}

1. Find/create this file via Claude Desktop settings -> Developer -> Edit Config.
2. Check the Model Context Protocol quickstart guide for more details.

Claude Code Installation

1. After installing Claude Code, run this command:

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

1. Refer to the Anthropic documentation for setting up MCP with Claude Code.

Windsurf Configuration

1. Add this configuration to your windsurf mcp_config.json file:

{
 "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 - for on-prem users
 }
 }
 }
}

1. See the Windsurf documentation for more information on MCP.

Smithery Installation

1. Install the CircleCI MCP Server for Claude Desktop automatically using Smithery:

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

Powerful CircleCI Features via Natural Language

Explore the features that will streamline your CI/CD workflow.

1. Get Build Failure Logs: Debug Faster

• Retrieve detailed logs from failed CircleCI builds instantly.
• Use CircleCI URLs or local project context to pinpoint failures.
• Example: "Get logs from [CircleCI Job URL]" OR "Find the latest failed pipeline on my current branch".
• Benefit: Shorten debugging time and resolve issues efficiently.

2. Find Flaky Tests: Improve Reliability

• Identify unreliable tests in your CircleCI projects leveraging the flaky test detection feature.
• Use your CircleCI project URL or local workspace details.
• Example: "Find flaky tests in [CircleCI Project URL]" OR "Find flaky tests in my current project".
• Benefit: Make data-driven decisions to boost test suite reliability.

3. Get Latest Pipeline Status: Stay Informed

• Retrieve the real-time status of your latest pipeline for a specific branch.
• Works with CircleCI Project URLs or local project context.
• Example: "Get the status of the latest pipeline for [CircleCI Project URL]" OR "Get the status of the latest pipeline for my current project".
• Benefit: Quickly check pipeline health without leaving your IDE.

4. Get Job Test Results: Analyze Test Metrics

• Retrieve test metadata for CircleCI jobs directly in your IDE.
• Supports CircleCI URLs (Job, Workflow, or Pipeline) and local project context.
• Example: "Get test results for [CircleCI Pipeline URL]" OR "Get test results for my current project on the main branch".
• Benefit: Analyze test failures, find slow tests, and check coverage effortlessly.

5. Config Helper: Validate Your CircleCI Configuration

• Check your .circleci/config.yml for errors and get configuration recommendations.
• Example: "Validate my CircleCI config".
• Benefit: Catch errors early and follow best practices for CircleCI configuration.

6. Create Prompt Template: Streamline AI Development

• Convert feature requirements into optimized prompt templates for AI applications.
• Example: "Create a prompt template for generating bedtime stories by age and topic".
• Benefit: Build efficient and robust AI-powered features.

7. Recommend Prompt Template Tests: Ensure AI Quality

• Generate test cases for prompt templates to validate their functionality.
• Example: "Generate tests for my bedtime story prompt template".
• Benefit: Ensure consistent AI responses and improve overall application quality.

Development Setup

Ready to contribute or customize? Here's how to get 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

Iterate with MCP Inspector

Leverage the MCP Inspector for rapid development.

1. Start Development Server:

pnpm watch

2. Launch Inspector (separate terminal): Follow instructions at Model Context Protocol.
3. Configure Environment: Add your CIRCLECI_TOKEN in the Inspector UI.

Run Tests

Ensure everything works smoothly.

1. Run Test Suite:

pnpm test

2. Run Tests in Watch Mode:

pnpm test:watch

Contribute

Check out the CONTRIBUTING.md file for guidelines on how to contribute to the project.

The CircleCI MCP Server unlocks a new way to interact with your CI/CD pipelines. By integrating natural language, you can simplify tasks, debug faster, and boost your development workflow. Start exploring today!