CircleCI MCP Server
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 logshttps://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide
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
Installing via Smithery
To install CircleCI MCP Server for Claude Desktop automatically via Smithery:
Cursor
Add the following to your cursor MCP config:
See the guide below for more information on using MCP servers with cursor:
https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers
Claude Desktop
Add the following to your claude_desktop_config.json:
To find/create this file, first open your claude desktop settings. Then click on "Developer" in the left-hand bar of the Settings pane, and then click on "Edit Config"
This will create a configuration file at:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
See the guide below for more information on using MCP servers with Claude Desktop:
https://modelcontextprotocol.io/quickstart/user
Claude Code
After installing Claude Code, run the following command:
See the guide below for more information on using MCP servers with Claude Code:
https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp
VS Code
Add the MCP server to your settings.json under
mcp -> servers:See the guide below for more information on using MCP servers with VS Code:
https://code.visualstudio.com/docs/copilot/chat/mcp-servers
Windsurf
Add the following to your windsurf mcp_config.json:
See the guide below for more information on using MCP servers with windsurf:
https://docs.windsurf.com/windsurf/mcp
Features
Supported Tools
get_build_failure_logsRetrieves detailed failure logs from CircleCI builds. This tool can be used in two ways:The tool returns formatted logs including:This is particularly useful for:
find_flaky_testsIdentifies flaky tests in your CircleCI project by analyzing test execution history. This leverages the flaky test detection feature described here: https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detectionThis tool can be used in two ways:The tool returns detailed information about flaky tests, including:This helps you:
config_helperAssists with CircleCI configuration tasks by providing guidance and validation. This tool helps you:The tool provides:This helps you:
Development
Getting Started
- Clone the repository:
- Install dependencies:
- Build the project:
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:
- In a separate terminal, launch the inspector:
- Configure the environment:
Testing
- Run the test suite:
- Run tests in watch mode during development:
For more detailed contribution guidelines, see CONTRIBUTING.md
CircleCI MCP Server
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 logshttps://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide
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
Installing via Smithery
To install CircleCI MCP Server for Claude Desktop automatically via Smithery:
Cursor
Add the following to your cursor MCP config:
See the guide below for more information on using MCP servers with cursor:
https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers
Claude Desktop
Add the following to your claude_desktop_config.json:
To find/create this file, first open your claude desktop settings. Then click on "Developer" in the left-hand bar of the Settings pane, and then click on "Edit Config"
This will create a configuration file at:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
See the guide below for more information on using MCP servers with Claude Desktop:
https://modelcontextprotocol.io/quickstart/user
Claude Code
After installing Claude Code, run the following command:
See the guide below for more information on using MCP servers with Claude Code:
https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp
VS Code
Add the MCP server to your settings.json under
mcp -> servers:See the guide below for more information on using MCP servers with VS Code:
https://code.visualstudio.com/docs/copilot/chat/mcp-servers
Windsurf
Add the following to your windsurf mcp_config.json:
See the guide below for more information on using MCP servers with windsurf:
https://docs.windsurf.com/windsurf/mcp
Features
Supported Tools
get_build_failure_logsRetrieves detailed failure logs from CircleCI builds. This tool can be used in two ways:The tool returns formatted logs including:This is particularly useful for:
find_flaky_testsIdentifies flaky tests in your CircleCI project by analyzing test execution history. This leverages the flaky test detection feature described here: https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detectionThis tool can be used in two ways:The tool returns detailed information about flaky tests, including:This helps you:
config_helperAssists with CircleCI configuration tasks by providing guidance and validation. This tool helps you:The tool provides:This helps you:
Development
Getting Started
- Clone the repository:
- Install dependencies:
- Build the project:
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:
- In a separate terminal, launch the inspector:
- Configure the environment:
Testing
- Run the test suite:
- Run tests in watch mode during development:
For more detailed contribution guidelines, see CONTRIBUTING.md