Integrate CircleCI with AI: A Developer's Guide to MCP Server for Enhanced Productivity

Tired of switching between your IDE and CircleCI to debug builds or analyze test results? The CircleCI MCP (Model Context Protocol) Server bridges the gap, enabling you to interact with CircleCI using natural language within your favorite IDE or code editor. This guide provides a comprehensive overview of how to install, configure, and utilize the CircleCI MCP Server to streamline your development workflow.

What is MCP and Why Should You Care?

Model Context Protocol (MCP) is a standardized protocol designed to manage context between Large Language Models (LLMs) and external systems. Think of it as a universal translator that allows AI tools to understand and interact with your development environment.

Key Benefits of Using MCP:

Increased Efficiency: Access CircleCI information and trigger actions directly from your IDE.
Natural Language Interaction: Use plain English to ask questions and retrieve data.
Improved Debugging: Quickly identify and analyze build failures without leaving your coding environment.
Enhanced Collaboration: Share context-aware insights with your team.

Prerequisites: Get Ready to Integrate

Before diving into the installation process, ensure you have the following:

pnpm: This package manager is essential for managing project dependencies. Learn more about pnpm.
Node.js: Version 18.0.0 or higher is required for running the MCP Server.
CircleCI API Token: Generate a personal API token with read access from your CircleCI account. Access this CircleCI API token generator for quick access.

Installation Guides: Configure Your IDE

The CircleCI MCP Server supports a variety of IDEs and code editors. Choose the guide that matches your preferred environment.

1. Cursor IDE

Enhance your Cursor IDE with seamless CircleCI integration.

Configuration: Add the following code snippet 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" // Optional - required for on-prem customers only
 }
 }
 }
}

CIRCLECI_TOKEN: Replace "your-circleci-token" with your actual CircleCI API token.
CIRCLECI_BASE_URL: Only required if you are using an on-premise CircleCI installation.

Learn more about configuring MCP servers with Cursor in the Cursor Documentation.

2. VS Code

Integrate CircleCI MCP Server into your VS Code environment for streamlined development.

Configuration: Add the following to your .vscode/mcp.json file:

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

Inputs: VS Code will prompt you for your CircleCI API token upon the first server start and store it securely.

For detailed instructions, refer to the VS Code documentation.

3. Claude Desktop

Connect CircleCI to your Claude Desktop application.

Configuration: Add this 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 - required for on-prem customers only
 }
 }
 }
}

Finding the config file: Access your Claude Desktop settings, click "Developer" in the left bar, and then "Edit Config" to create or open the configuration file.
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Get more information on using MCP servers with Claude Desktop from Model Context Protocol's quickstart guide.

4. Claude Code

Integrate CircleCI functionality directly into Claude Code.

Command: Execute the following command in your terminal:

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

Seamless Integration: This command adds the CircleCI MCP Server to your Claude Code setup.

For detailed instructions, consult the Claude Code tutorials.

5. Windsurf

Configure the CircleCI MCP Server within your Windsurf environment.

Configuration: Add the following snippet to your windsurf mcp_config.json:

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

Configuration: This setup allows Windsurf to interact with your CircleCI projects.

Refer to the Windsurf documentation for additional guidance.

6. Smithery Installation (Claude Desktop)

Automate the installation process for Claude Desktop using Smithery.

Command: Run the following command in your terminal:

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

Automated Setup: Smithery simplifies the installation process for Claude Desktop.

Core Features: Unleash the Power of CircleCI MCP Server

The CircleCI MCP Server offers a suite of powerful tools to enhance your development workflow.

1. `get_build_failure_logs`: Diagnose Build Failures Instantly

This tool retrieves detailed failure logs from CircleCI builds, helping you quickly identify the root cause of issues.

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"
Using Local Project Context:
- Works from your local workspace.
- Provide the workspace root path, Git remote URL, and branch name.
- Example: "Find the latest failed pipeline on my current branch"

Benefits:

Debug failed builds more efficiently.
Analyze test failures with detailed context.
Investigate deployment issues directly from your IDE.

2. `find_flaky_tests`: Identify Unreliable Tests

This tool identifies flaky tests in your CircleCI project, enabling you to improve the reliability of your test suite. Leveraging the flaky test detection feature.

Using CircleCI Project URL:
- Provide the project URL from CircleCI.
- Example: "Find flaky tests in https://app.circleci.com/pipelines/github/org/repo"
Using Local Project Context:
- Works from your local workspace.
- Provide the workspace root path and Git remote URL.
- Example: "Find flaky tests in my current project"

Benefits:

Identify unreliable tests.
Gain detailed context about test failures.
Make data-driven decisions regarding test improvements.

3. `get_latest_pipeline_status`: Stay Informed About Your Pipelines

This tool retrieves the status of the latest pipeline for a given branch, keeping you informed about your project's health.

Using CircleCI Project URL:
- Provide the project URL from CircleCI.
- Example: "Get the status of the latest pipeline for https://app.circleci.com/pipelines/github/org/repo"
Using Local Project Context:
- Works from your local workspace.
- Provide the workspace root path, Git remote URL, and branch name.
- Example: "Get the status of the latest pipeline for my current project"

Example Output:

---
Workflow: build
Status: success
Duration: 5 minutes
Created: 4/20/2025, 10:15:30 AM
Stopped: 4/20/2025, 10:20:45 AM
---
Workflow: test
Status: running
Duration: unknown
Created: 4/20/2025, 10:21:00 AM
Stopped: in progress

Benefits:

Quickly check the status of the latest pipeline.
Monitor specific branches.
Stay informed without leaving your IDE.

4. `get_job_test_results`: Analyze Test Results Effortlessly

This tool retrieves test metadata for CircleCI jobs, allowing you to analyze test results within your IDE.

Using CircleCI URL (Recommended):
- Provide a CircleCI URL in one of the following formats:
  - Job URL: "https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789"
  - Workflow URL: "https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def"
  - Pipeline URL: "https://app.circleci.com/pipelines/github/org/repo/123"
- Example: "Get test results for https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def"
Using Local Project Context:
- Works from your local workspace.
- Provide the workspace root path, Git remote URL, and branch name.
- Example: "Get test results for my current project on the main branch"

Benefits:

Analyze test failures without visiting the CircleCI web UI.
Identify patterns in test failures.
Find slow tests for optimization.

5. `config_helper`: Streamline Configuration

This tool helps with CircleCI configuration tasks by providing guidance and validation.

Validate CircleCI Config:
- Checks your .circleci/config.yml for syntax and semantic errors.
- Example: "Validate my CircleCI config"

Benefits:

Catch configuration errors early.
Learn CircleCI configuration best practices.
Troubleshoot configuration issues effectively.

6. `create_prompt_template`: Generate AI Prompts

Helps generate structured prompt templates for AI-enabled applications based on feature requirements.

Converts Feature Requirements to Structured Prompts:
- Transforms user requirements into optimized prompt templates.
- Example: "Create a prompt template for generating bedtime stories by age and topic"

Benefits:

Create effective prompts for AI applications.
Standardize input parameters for consistent results.
Build robust AI-powered features.

7. `recommend_prompt_template_tests`: Test AI Prompts

Generates test cases for prompt templates to ensure they produce expected results.

Provides Test Cases for Prompt Templates:
- Creates diverse test scenarios based on your prompt template and context schema.
- Example: "Generate tests for my bedtime story prompt template"

Benefits:

Validate prompt template functionality.
Ensure consistent AI responses across inputs.
Identify edge cases and potential issues.

Development: Contribute to the Project

Want to contribute to the CircleCI MCP Server? Here's how to get 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 MCP Inspector provides an interface iterating seamlessly with the MCP Server. You can explore more on the Model Context Protocol.

Start the development server:

pnpm watch # Keep this running in one terminal

Launch the inspector in a separate terminal:
Configure the environment:
- Add your CIRCLECI_TOKEN to the Environment Variables section in the inspector UI. Ensure it has read access to your CircleCI projects.
- Optionally, 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 detailed contribution guidelines, see CONTRIBUTING.md.

Conclusion: Elevate Your CircleCI Experience

The CircleCI MCP Server revolutionizes how developers interact with CircleCI. By integrating seamlessly with popular IDEs and providing natural language access to critical information, it empowers teams to debug faster, improve test reliability, and optimize their development workflows. Embrace the power of AI-driven integration and unlock new levels of productivity.

Integrate CircleCI with AI: A Developer's Guide to MCP Server for Enhanced Productivity

What is MCP and Why Should You Care?

Key Benefits of Using MCP:

Increased Efficiency: Access CircleCI information and trigger actions directly from your IDE.
Natural Language Interaction: Use plain English to ask questions and retrieve data.
Improved Debugging: Quickly identify and analyze build failures without leaving your coding environment.
Enhanced Collaboration: Share context-aware insights with your team.

Prerequisites: Get Ready to Integrate

Before diving into the installation process, ensure you have the following:

pnpm: This package manager is essential for managing project dependencies. Learn more about pnpm.
Node.js: Version 18.0.0 or higher is required for running the MCP Server.
CircleCI API Token: Generate a personal API token with read access from your CircleCI account. Access this CircleCI API token generator for quick access.

Installation Guides: Configure Your IDE

The CircleCI MCP Server supports a variety of IDEs and code editors. Choose the guide that matches your preferred environment.

1. Cursor IDE

Enhance your Cursor IDE with seamless CircleCI integration.

Configuration: Add the following code snippet 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" // Optional - required for on-prem customers only
 }
 }
 }
}

CIRCLECI_TOKEN: Replace "your-circleci-token" with your actual CircleCI API token.
CIRCLECI_BASE_URL: Only required if you are using an on-premise CircleCI installation.

Learn more about configuring MCP servers with Cursor in the Cursor Documentation.

2. VS Code

Integrate CircleCI MCP Server into your VS Code environment for streamlined development.

Configuration: Add the following to your .vscode/mcp.json file:

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

Inputs: VS Code will prompt you for your CircleCI API token upon the first server start and store it securely.

For detailed instructions, refer to the VS Code documentation.

3. Claude Desktop

Connect CircleCI to your Claude Desktop application.

Configuration: Add this 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 - required for on-prem customers only
 }
 }
 }
}

Finding the config file: Access your Claude Desktop settings, click "Developer" in the left bar, and then "Edit Config" to create or open the configuration file.
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Get more information on using MCP servers with Claude Desktop from Model Context Protocol's quickstart guide.

4. Claude Code

Integrate CircleCI functionality directly into Claude Code.

Command: Execute the following command in your terminal:

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

Seamless Integration: This command adds the CircleCI MCP Server to your Claude Code setup.

For detailed instructions, consult the Claude Code tutorials.

5. Windsurf

Configure the CircleCI MCP Server within your Windsurf environment.

Configuration: Add the following snippet to your windsurf mcp_config.json:

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

Configuration: This setup allows Windsurf to interact with your CircleCI projects.

Refer to the Windsurf documentation for additional guidance.

6. Smithery Installation (Claude Desktop)

Automate the installation process for Claude Desktop using Smithery.

Command: Run the following command in your terminal:

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

Automated Setup: Smithery simplifies the installation process for Claude Desktop.

Core Features: Unleash the Power of CircleCI MCP Server

The CircleCI MCP Server offers a suite of powerful tools to enhance your development workflow.

1. `get_build_failure_logs`: Diagnose Build Failures Instantly

This tool retrieves detailed failure logs from CircleCI builds, helping you quickly identify the root cause of issues.

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"
Using Local Project Context:
- Works from your local workspace.
- Provide the workspace root path, Git remote URL, and branch name.
- Example: "Find the latest failed pipeline on my current branch"

Benefits:

Debug failed builds more efficiently.
Analyze test failures with detailed context.
Investigate deployment issues directly from your IDE.

2. `find_flaky_tests`: Identify Unreliable Tests

This tool identifies flaky tests in your CircleCI project, enabling you to improve the reliability of your test suite. Leveraging the flaky test detection feature.

Using CircleCI Project URL:
- Provide the project URL from CircleCI.
- Example: "Find flaky tests in https://app.circleci.com/pipelines/github/org/repo"
Using Local Project Context:
- Works from your local workspace.
- Provide the workspace root path and Git remote URL.
- Example: "Find flaky tests in my current project"

Benefits:

Identify unreliable tests.
Gain detailed context about test failures.
Make data-driven decisions regarding test improvements.

3. `get_latest_pipeline_status`: Stay Informed About Your Pipelines

This tool retrieves the status of the latest pipeline for a given branch, keeping you informed about your project's health.

Using CircleCI Project URL:
- Provide the project URL from CircleCI.
- Example: "Get the status of the latest pipeline for https://app.circleci.com/pipelines/github/org/repo"
Using Local Project Context:
- Works from your local workspace.
- Provide the workspace root path, Git remote URL, and branch name.
- Example: "Get the status of the latest pipeline for my current project"

Example Output:

---
Workflow: build
Status: success
Duration: 5 minutes
Created: 4/20/2025, 10:15:30 AM
Stopped: 4/20/2025, 10:20:45 AM
---
Workflow: test
Status: running
Duration: unknown
Created: 4/20/2025, 10:21:00 AM
Stopped: in progress

Benefits:

Quickly check the status of the latest pipeline.
Monitor specific branches.
Stay informed without leaving your IDE.

4. `get_job_test_results`: Analyze Test Results Effortlessly

This tool retrieves test metadata for CircleCI jobs, allowing you to analyze test results within your IDE.

Using CircleCI URL (Recommended):
- Provide a CircleCI URL in one of the following formats:
  - Job URL: "https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789"
  - Workflow URL: "https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def"
  - Pipeline URL: "https://app.circleci.com/pipelines/github/org/repo/123"
- Example: "Get test results for https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def"
Using Local Project Context:
- Works from your local workspace.
- Provide the workspace root path, Git remote URL, and branch name.
- Example: "Get test results for my current project on the main branch"

Benefits:

Analyze test failures without visiting the CircleCI web UI.
Identify patterns in test failures.
Find slow tests for optimization.

5. `config_helper`: Streamline Configuration

This tool helps with CircleCI configuration tasks by providing guidance and validation.

Validate CircleCI Config:
- Checks your .circleci/config.yml for syntax and semantic errors.
- Example: "Validate my CircleCI config"

Benefits:

Catch configuration errors early.
Learn CircleCI configuration best practices.
Troubleshoot configuration issues effectively.

6. `create_prompt_template`: Generate AI Prompts

Helps generate structured prompt templates for AI-enabled applications based on feature requirements.

Converts Feature Requirements to Structured Prompts:
- Transforms user requirements into optimized prompt templates.
- Example: "Create a prompt template for generating bedtime stories by age and topic"

Benefits:

Create effective prompts for AI applications.
Standardize input parameters for consistent results.
Build robust AI-powered features.

7. `recommend_prompt_template_tests`: Test AI Prompts

Generates test cases for prompt templates to ensure they produce expected results.

Provides Test Cases for Prompt Templates:
- Creates diverse test scenarios based on your prompt template and context schema.
- Example: "Generate tests for my bedtime story prompt template"

Benefits:

Validate prompt template functionality.
Ensure consistent AI responses across inputs.
Identify edge cases and potential issues.

Development: Contribute to the Project

Want to contribute to the CircleCI MCP Server? Here's how to get 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 MCP Inspector provides an interface iterating seamlessly with the MCP Server. You can explore more on the Model Context Protocol.

Start the development server:

pnpm watch # Keep this running in one terminal

Launch the inspector in a separate terminal:
Configure the environment:
- Add your CIRCLECI_TOKEN to the Environment Variables section in the inspector UI. Ensure it has read access to your CircleCI projects.
- Optionally, set your CircleCI Base URL. Defaults to https://circleci.com.