https://github.com/circleci-public/mcp-server-circleci
A specialized server implementation for the Model Context Protocol (MCP) designed to integrate with CircleCI's development workflow. This project serves as a bridge between CircleCI's infrastructure and the Model Context Protocol, enabling enhanced AI-powered development experiences.
https://github.com/circleci-public/mcp-server-circleci
mcp-server modelcontextprotocol
Last synced: 12 days ago
JSON representation
A specialized server implementation for the Model Context Protocol (MCP) designed to integrate with CircleCI's development workflow. This project serves as a bridge between CircleCI's infrastructure and the Model Context Protocol, enabling enhanced AI-powered development experiences.
- Host: GitHub
- URL: https://github.com/circleci-public/mcp-server-circleci
- Owner: CircleCI-Public
- License: apache-2.0
- Created: 2025-03-26T18:31:55.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-04-11T21:02:23.000Z (14 days ago)
- Last Synced: 2025-04-13T20:55:58.126Z (12 days ago)
- Topics: mcp-server, modelcontextprotocol
- Language: TypeScript
- Homepage:
- Size: 301 KB
- Stars: 10
- Watchers: 7
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# CircleCI MCP Server
[](https://github.com/CircleCI-Public/mcp-server-circleci/blob/main/LICENSE)
[](https://dl.circleci.com/status-badge/redirect/gh/CircleCI-Public/mcp-server-circleci/tree/main)
[](https://www.npmjs.com/package/@circleci/mcp-server-circleci)
Model Context Protocol (MCP) is a [new, standardized protocol](https://modelcontextprotocol.io/introduction) for managing context between large language models (LLMs) and external systems. In this repository, we provide an MCP Server for [CircleCI](https://circleci.com).
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](https://pnpm.io/installation)
- Node.js >= v18.0.0
- CircleCI API token - you can generate one through the CircleCI. [Learn more](https://circleci.com/docs/managing-api-tokens/) or [click here](https://app.circleci.com/settings/user/tokens) for quick access.
## Installation
### Cursor
Add the following to your cursor 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
}
}
}
}
```
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:
```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
}
}
}
}
```
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
### VS Code
Add the MCP server to your settings.json under `mcp -> servers`:
```json
"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
}
}
```
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:
```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
}
}
}
}
```
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_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
- `find_flaky_tests`
Identifies 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-detection
This tool can be used in two ways:
1. Using CircleCI Project URL:
- Provide the project URL directly from CircleCI
- Example: "Find flaky tests in https://app.circleci.com/pipelines/github/org/repo"
2. Using Local Project Context:
- Works from your local workspace by providing:
- Workspace root path
- Git remote URL
- Example: "Find flaky tests in my current project"
The tool returns detailed information about flaky tests, including:
- Test names and file locations
- Failure messages and contexts
This helps you:
- Identify unreliable tests in your test suite
- Get detailed context about test failures
- Make data-driven decisions about test improvements
# Development
## Getting Started
1. Clone the repository:
```bash
git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci
```
2. Install dependencies:
```bash
pnpm install
```
3. Build the project:
```bash
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
1. Start the development server:
```bash
pnpm watch # Keep this running in one terminal
```
2. In a separate terminal, launch the inspector:
```bash
pnpm inspector
```
3. 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:
```bash
pnpm test
```
- Run tests in watch mode during development:
```bash
pnpm test:watch
```
For more detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)