CircleCI/mcp-server-circleci

> **This package is deprecated. Please migrate.**
>
> @circleci/mcp-server-circleci is no longer receiving feature work. Use CircleCI's **hosted MCP server** or the **CircleCI CLI MCP** instead — see the **CircleCI MCP overview**.
>
> This repository will be archived. Existing versions remain installable from npm, but running an unmaintained server that holds a CircleCI Personal API Token is not recommended.
>
> If you are running the **self-managed remote transport** (start=remote), migrate first: the hosted server is its direct replacement and removes the need to operate a network-facing service that brokers your org's token.
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.
Use Cursor, Windsurf, Copilot, Claude, or any MCP-compatible client to interact with CircleCI using natural language — without leaving your IDE.
Tools
| Tool | Description |
|------|-------------|
| config_helper | Validate and get guidance for your CircleCI configuration |
| download_usage_api_data | Download usage data from the CircleCI Usage API |
| find_flaky_tests | Identify flaky tests by analyzing test execution history |
| find_underused_resource_classes | Find jobs with underused compute resources |
| get_build_failure_logs | Retrieve detailed failure logs from CircleCI builds |
| get_job_test_results | Retrieve test metadata and results for CircleCI jobs |
| get_latest_pipeline_status | Get the status of the latest pipeline for a branch |
| list_artifacts | List artifacts produced by a CircleCI job |
| list_component_versions | List all versions for a CircleCI component |
| list_followed_projects | List all CircleCI projects you're following |
| rerun_workflow | Rerun a workflow from start or from the failed job |
| run_pipeline | Trigger a pipeline to run |
| run_rollback_pipeline | Trigger a rollback for a project |
Installation
> **Team / centralized deployment:** To run one shared remote server for your org (Kubernetes, Docker, etc.) with per-developer or shared CircleCI tokens, see Self-Managed Remote MCP Server.
Cursor
**Prerequisites:**
- CircleCI Personal API token (learn more)
- NPX: Node.js >= v18 and pnpm
- Docker: Docker
Using NPX in a local MCP Server
Add the following to your Cursor MCP config:
> CIRCLECI_BASE_URL is optional — required for on-prem customers only.
> MAX_MCP_OUTPUT_LENGTH is optional — maximum output length for MCP responses (default: 50000).
Using Docker in a local MCP Server
Add the following to your Cursor MCP config:
Using a Self-Managed Remote MCP Server
See Self-Managed Remote MCP Server. Use the per-user client configuration and add it to your Cursor MCP config (Cursor Settings → MCP).
VS Code
**Prerequisites:**
- CircleCI Personal API token (learn more)
- NPX: Node.js >= v18 and pnpm
- Docker: Docker
Using NPX in a local MCP Server
Add the following to .vscode/mcp.json in your project:
> 💡 Inputs are prompted on first server start, then stored securely by VS Code.
Using Docker in a local MCP Server
Add the following to .vscode/mcp.json in your project:
Using a Self-Managed Remote MCP Server
See Self-Managed Remote MCP Server. Use the per-user client configuration in .vscode/mcp.json.
Claude Desktop
**Prerequisites:**
- CircleCI Personal API token (learn more)
- NPX: Node.js >= v18 and pnpm
- Docker: Docker
Using NPX in a local MCP Server
Add the following to your claude_desktop_config.json:
Using Docker in a local MCP Server
Add the following to your claude_desktop_config.json:
Using a Self-Managed Remote MCP Server
See Self-Managed Remote MCP Server. Create a wrapper script as shown in Claude Desktop and CLI clients, then point your claude_desktop_config.json at it.
To find or create your config file, open Claude Desktop settings, click **Developer** in the left sidebar, then click **Edit Config**. The config file is located at:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
For more information: https://modelcontextprotocol.io/quickstart/user
Claude Code
**Prerequisites:**
- CircleCI Personal API token (learn more)
- NPX: Node.js >= v18 and pnpm
- Docker: Docker
Using NPX in a local MCP Server
Using Docker in a local MCP Server
Using a Self-Managed Remote MCP Server
See Self-Managed Remote MCP Server and the Claude Code client setup there.