# 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 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: \`\`\`bash claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci \`\`\` 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\`: \`\`\`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)