--- slug: "circleci-mcp-server" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/circleci-public/mcp-server-circleci@main/README.md" repo: "https://github.com/circleci-public/mcp-server-circleci" source_file: "README.md" branch: "main" --- > [!IMPORTANT] > This repository is deprecated. The CircleCI MCP server is now built into the CircleCI CLI. Visit **[cli.circleci.com](https://cli.circleci.com)** to get started. # CircleCI MCP Server [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/CircleCI-Public/mcp-server-circleci/blob/main/LICENSE) [![CircleCI](https://dl.circleci.com/status-badge/img/gh/CircleCI-Public/mcp-server-circleci/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/CircleCI-Public/mcp-server-circleci/tree/main) [![npm](https://img.shields.io/npm/v/@circleci/mcp-server-circleci?logo=npm)](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). 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`](#config_helper) | Validate and get guidance for your CircleCI configuration | | [`download_usage_api_data`](#download_usage_api_data) | Download usage data from the CircleCI Usage API | | [`find_flaky_tests`](#find_flaky_tests) | Identify flaky tests by analyzing test execution history | | [`find_underused_resource_classes`](#find_underused_resource_classes) | Find jobs with underused compute resources | | [`get_build_failure_logs`](#get_build_failure_logs) | Retrieve detailed failure logs from CircleCI builds | | [`get_job_test_results`](#get_job_test_results) | Retrieve test metadata and results for CircleCI jobs | | [`get_latest_pipeline_status`](#get_latest_pipeline_status) | Get the status of the latest pipeline for a branch | | [`list_artifacts`](#list_artifacts) | List artifacts produced by a CircleCI job | | [`list_component_versions`](#list_component_versions) | List all versions for a CircleCI component | | [`list_followed_projects`](#list_followed_projects) | List all CircleCI projects you're following | | [`rerun_workflow`](#rerun_workflow) | Rerun a workflow from start or from the failed job | | [`run_pipeline`](#run_pipeline) | Trigger a pipeline to run | | [`run_rollback_pipeline`](#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](#self-managed-remote-mcp-server).
Cursor **Prerequisites:** - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/)) - NPX: [Node.js >= v18](https://nodejs.org/) and [pnpm](https://pnpm.io/installation) - Docker: [Docker](https://docs.docker.com/get-docker/) #### Using NPX in a local MCP Server Add the following to your Cursor MCP config: ```json { "mcpServers": { "circleci-mcp-server": { "command": "npx", "args": ["-y", "@circleci/mcp-server-circleci@latest"], "env": { "CIRCLECI_TOKEN": "your-circleci-token", "CIRCLECI_BASE_URL": "https://circleci.com", "MAX_MCP_OUTPUT_LENGTH": "50000" } } } } ``` > `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: ```json { "mcpServers": { "circleci-mcp-server": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "CIRCLECI_TOKEN", "-e", "CIRCLECI_BASE_URL", "-e", "MAX_MCP_OUTPUT_LENGTH", "circleci/mcp-server-circleci" ], "env": { "CIRCLECI_TOKEN": "your-circleci-token", "CIRCLECI_BASE_URL": "https://circleci.com", "MAX_MCP_OUTPUT_LENGTH": "50000" } } } } ``` #### Using a Self-Managed Remote MCP Server See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use the [per-user client configuration](#client-configuration-per-user-tokens) and add it to your Cursor MCP config (`Cursor Settings → MCP`).
VS Code **Prerequisites:** - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/)) - NPX: [Node.js >= v18](https://nodejs.org/) and [pnpm](https://pnpm.io/installation) - Docker: [Docker](https://docs.docker.com/get-docker/) #### Using NPX in a local MCP Server Add the following to `.vscode/mcp.json` in your project: ```json { "inputs": [ { "type": "promptString", "id": "circleci-token", "description": "CircleCI API Token", "password": true }, { "type": "promptString", "id": "circleci-base-url", "description": "CircleCI Base URL", "default": "https://circleci.com" } ], "servers": { "circleci-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@circleci/mcp-server-circleci@latest"], "env": { "CIRCLECI_TOKEN": "${input:circleci-token}", "CIRCLECI_BASE_URL": "${input:circleci-base-url}" } } } } ``` > 💡 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: ```json { "inputs": [ { "type": "promptString", "id": "circleci-token", "description": "CircleCI API Token", "password": true }, { "type": "promptString", "id": "circleci-base-url", "description": "CircleCI Base URL", "default": "https://circleci.com" } ], "servers": { "circleci-mcp-server": { "type": "stdio", "command": "docker", "args": [ "run", "--rm", "-i", "-e", "CIRCLECI_TOKEN", "-e", "CIRCLECI_BASE_URL", "circleci/mcp-server-circleci" ], "env": { "CIRCLECI_TOKEN": "${input:circleci-token}", "CIRCLECI_BASE_URL": "${input:circleci-base-url}" } } } } ``` #### Using a Self-Managed Remote MCP Server See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use the [per-user client configuration](#client-configuration-per-user-tokens) in `.vscode/mcp.json`.
Claude Desktop **Prerequisites:** - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/)) - NPX: [Node.js >= v18](https://nodejs.org/) and [pnpm](https://pnpm.io/installation) - Docker: [Docker](https://docs.docker.com/get-docker/) #### Using NPX in a local MCP Server Add the following to your `claude_desktop_config.json`: ```json { "mcpServers": { "circleci-mcp-server": { "command": "npx", "args": ["-y", "@circleci/mcp-server-circleci@latest"], "env": { "CIRCLECI_TOKEN": "your-circleci-token", "CIRCLECI_BASE_URL": "https://circleci.com", "MAX_MCP_OUTPUT_LENGTH": "50000" } } } } ``` #### Using Docker in a local MCP Server Add the following to your `claude_desktop_config.json`: ```json { "mcpServers": { "circleci-mcp-server": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "CIRCLECI_TOKEN", "-e", "CIRCLECI_BASE_URL", "-e", "MAX_MCP_OUTPUT_LENGTH", "circleci/mcp-server-circleci" ], "env": { "CIRCLECI_TOKEN": "your-circleci-token", "CIRCLECI_BASE_URL": "https://circleci.com", "MAX_MCP_OUTPUT_LENGTH": "50000" } } } } ``` #### Using a Self-Managed Remote MCP Server See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Create a wrapper script as shown in [Claude Desktop and CLI clients](#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](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/)) - NPX: [Node.js >= v18](https://nodejs.org/) and [pnpm](https://pnpm.io/installation) - Docker: [Docker](https://docs.docker.com/get-docker/) #### Using NPX in a local MCP Server ```bash claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest ``` #### Using Docker in a local MCP Server ```bash claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com -- docker run --rm -i -e CIRCLECI_TOKEN -e CIRCLECI_BASE_URL circleci/mcp-server-circleci ``` #### Using a Self-Managed Remote MCP Server See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server) and the [Claude Code](#claude-code) client setup there.
Windsurf **Prerequisites:** - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/)) - NPX: [Node.js >= v18](https://nodejs.org/) and [pnpm](https://pnpm.io/installation) - Docker: [Docker](https://docs.docker.com/get-docker/) #### Using NPX in a local MCP Server Add the following to your Windsurf `mcp_config.json`: ```json { "mcpServers": { "circleci-mcp-server": { "command": "npx", "args": ["-y", "@circleci/mcp-server-circleci@latest"], "env": { "CIRCLECI_TOKEN": "your-circleci-token", "CIRCLECI_BASE_URL": "https://circleci.com", "MAX_MCP_OUTPUT_LENGTH": "50000" } } } } ``` #### Using Docker in a local MCP Server Add the following to your Windsurf `mcp_config.json`: ```json { "mcpServers": { "circleci-mcp-server": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "CIRCLECI_TOKEN", "-e", "CIRCLECI_BASE_URL", "-e", "MAX_MCP_OUTPUT_LENGTH", "circleci/mcp-server-circleci" ], "env": { "CIRCLECI_TOKEN": "your-circleci-token", "CIRCLECI_BASE_URL": "https://circleci.com", "MAX_MCP_OUTPUT_LENGTH": "50000" } } } } ``` #### Using a Self-Managed Remote MCP Server See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use the [per-user client configuration](#client-configuration-per-user-tokens) in your Windsurf `mcp_config.json`. For more information: https://docs.windsurf.com/windsurf/mcp
Amazon Q Developer CLI **Prerequisites:** - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/)) - NPX: [Node.js >= v18](https://nodejs.org/) and [pnpm](https://pnpm.io/installation) MCP client configuration in Amazon Q Developer is stored in JSON format in a file named `mcp.json`. Two levels of configuration are supported: - **Global:** `~/.aws/amazonq/mcp.json` — applies to all workspaces - **Workspace:** `.amazonq/mcp.json` — specific to the current workspace If both files exist, their contents are merged. In case of conflict, the workspace config takes precedence. #### Using NPX in a local MCP Server Edit `~/.aws/amazonq/mcp.json` or create `.amazonq/mcp.json` with the following: ```json { "mcpServers": { "circleci-local": { "command": "npx", "args": [ "-y", "@circleci/mcp-server-circleci@latest" ], "env": { "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN", "CIRCLECI_BASE_URL": "https://circleci.com", "MAX_MCP_OUTPUT_LENGTH": "50000" }, "timeout": 60000 } } } ``` #### Using a Self-Managed Remote MCP Server See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use a wrapper script as shown in [Claude Desktop and CLI clients](#claude-desktop-and-cli-clients), then register it with `q mcp add`.
Amazon Q Developer in the IDE **Prerequisites:** - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/)) - NPX: [Node.js >= v18](https://nodejs.org/) and [pnpm](https://pnpm.io/installation) #### Using NPX in a local MCP Server Edit `~/.aws/amazonq/mcp.json` or create `.amazonq/mcp.json` with the following: ```json { "mcpServers": { "circleci-local": { "command": "npx", "args": [ "-y", "@circleci/mcp-server-circleci@latest" ], "env": { "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN", "CIRCLECI_BASE_URL": "https://circleci.com", "MAX_MCP_OUTPUT_LENGTH": "50000" }, "timeout": 60000 } } } ``` #### Using a Self-Managed Remote MCP Server See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use a wrapper script as shown in [Claude Desktop and CLI clients](#claude-desktop-and-cli-clients), then add it via the MCP configuration UI: 1. [Access the MCP configuration UI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/mcp-ide.html#mcp-ide-configuration-access-ui) 2. Choose the **+** symbol 3. Select scope: **global** or **local** 4. Enter a name (e.g. `circleci-remote-mcp`) 5. Select transport protocol: **stdio** 6. Enter the command path to your script 7. Click **Save**
Smithery To install CircleCI MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@CircleCI-Public/mcp-server-circleci): ```bash npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude ```
## Self-Managed Remote MCP Server Run the MCP server centrally (for example on Kubernetes or Docker) so your team shares one deployment. Choose how developers authenticate: ### Choose a deployment mode | Mode | When to use | Server setup | Client setup | CircleCI audit trail | |------|-------------|--------------|--------------|----------------------| | **Per-user tokens** (recommended) | Teams with SSO-backed Personal API Tokens | `REQUIRE_REQUEST_TOKEN=true`, no server PAT | Each dev forwards their PAT | Per developer | | **Shared token** (interim) | Quick rollout, single service identity OK | `CIRCLECI_TOKEN` on server, `REQUIRE_REQUEST_TOKEN=false` (explicit opt-out) | No auth header needed | Single shared identity | > **Security:** Request authentication is **on by default** in remote mode. The shared-token mode disables it (`REQUIRE_REQUEST_TOKEN=false`), making every caller able to act as the server's `CIRCLECI_TOKEN` identity with no credentials. Only enable it on a network you fully trust, and prefer per-user tokens otherwise. Terminating TLS at an ingress provides encryption, not authentication. ### 1. Deploy the server Both modes use remote HTTP mode (`start=remote`). Publish port `8000` (or your chosen port). **Per-user tokens (recommended) — accessed via `mcp-remote` from localhost:** ```bash docker run --rm -p 8000:8000 \ -e start=remote \ -e port=8000 \ -e REQUIRE_REQUEST_TOKEN=true \ circleci/mcp-server-circleci ``` **Per-user tokens (recommended) — accessed via `mcp-remote` from a public hostname:** ```bash docker run --rm -p 8000:8000 \ -e start=remote \ -e port=8000 \ -e REQUIRE_REQUEST_TOKEN=true \ -e MCP_ALLOWED_HOSTS=my-mcp.example.com \ circleci/mcp-server-circleci ``` **Shared token (interim) — accessed via `mcp-remote` from a public hostname:** ```bash docker run --rm -p 8000:8000 \ -e start=remote \ -e port=8000 \ -e CIRCLECI_TOKEN=your-shared-circleci-pat \ -e REQUIRE_REQUEST_TOKEN=false \ -e MCP_ALLOWED_HOSTS=my-mcp.example.com \ circleci/mcp-server-circleci ``` **Environment variables:** | Variable | Description | |----------|-------------| | `start=remote` | Starts the HTTP+SSE MCP server instead of stdio | | `port` | Listening port inside the container (default: `8000`) | | `REQUIRE_REQUEST_TOKEN` | Reject requests without `Authorization: Bearer` or `Circle-Token` header. Defaults to required; set `REQUIRE_REQUEST_TOKEN=false` to allow unauthenticated requests (shared-token mode) | | `CIRCLECI_TOKEN` | Shared fallback PAT for all requests when per-user headers are not sent | | `CIRCLECI_BASE_URL` | Optional — required for on-prem only (default: `https://circleci.com`) | | `DISABLE_TELEMETRY=true` | Opt out of usage metrics export | | `MCP_ALLOWED_HOSTS` | Comma-separated list of additional `Host` header values to allow (e.g. `my-mcp.example.com,my-mcp.example.com:443`). Loopback hostnames are always allowed. Required for any non-loopback deployment. | | `MCP_ALLOWED_ORIGINS` | Comma-separated list of additional `Origin` header values to allow (e.g. `https://my-app.example.com`). Loopback origins are always allowed. Only needed when a browser directly reaches this server (not via `mcp-remote`). | | `MCP_BIND_HOST` | Network interface to bind to (default: `0.0.0.0`). Set to `127.0.0.1` to restrict to loopback only (not compatible with Docker `-p` port mapping). | > **DNS-rebinding protection:** The remote transport validates the `Host` header on every `/mcp` request. By default only loopback addresses (`localhost`, `127.0.0.1`, `[::1]`) are accepted. **Public deployments must set `MCP_ALLOWED_HOSTS`** to the hostname clients use, or all `/mcp` requests will receive `403 Forbidden`. The `/ping` health-check endpoint is not guarded so load-balancer probes continue to work regardless of `Host`. > > The `Origin` header (sent by browsers) is also validated when present. Non-browser clients such as `mcp-remote` never send `Origin`, so they are unaffected by this check. > > **Behind a reverse proxy:** If your proxy rewrites `Host` to the backend address (nginx's default), add `proxy_set_header Host $host;` to pass the original hostname through, then set `MCP_ALLOWED_HOSTS` to that public hostname. Alternatively, set `MCP_ALLOWED_HOSTS` to whatever hostname the proxy does forward. The server accepts per-request tokens via: - `Authorization: Bearer ` - `Circle-Token: ` If a client sends a header token, it takes precedence over `CIRCLECI_TOKEN` on the server. Telemetry metrics recorded during a request are exported using the same token as that request. ### 2. Configure clients Most MCP clients only support local (stdio) processes. Use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), a third-party stdio-to-HTTP bridge, to connect them to your remote server. > **URL scheme:** Use `http://localhost:8000/mcp` with `--allow-http` for local testing. In production, terminate TLS at your ingress/load balancer and use `https://your-host/mcp` without `--allow-http`. > **Windows:** Avoid spaces around the colon in `--header` values. Put the full `Bearer ` value in an environment variable. > **Security:** Examples use `npx` for convenience. For production or team rollouts, pin a specific version in your MCP config (for example `mcp-remote@0.1.38` instead of `mcp-remote`). Do not use versions below `0.1.16` ([CVE-2025-6514](https://www.npmjs.com/package/mcp-remote)). #### Client configuration: per-user tokens Each developer forwards their own CircleCI Personal API Token on every request: ```json { "inputs": [ { "type": "promptString", "id": "circleci-token", "description": "CircleCI API Token", "password": true } ], "mcpServers": { "circleci-mcp-server-remote": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:8000/mcp", "--allow-http", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer ${input:circleci-token}" } } } } ``` Replace `http://localhost:8000/mcp` with your team's server URL. Cursor and VS Code support `${input:...}` prompts; other clients can set `AUTH_HEADER` directly. #### Client configuration: shared token When the server has `CIRCLECI_TOKEN` set and is started with `REQUIRE_REQUEST_TOKEN=false` (request auth is on by default and must be explicitly disabled), clients do not need to send a token: ```json { "mcpServers": { "circleci-mcp-server-remote": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:8000/mcp", "--allow-http" ] } } } ``` #### Claude Desktop and CLI clients Create a wrapper script (e.g. `circleci-remote-mcp.sh`): ```bash #!/bin/bash export AUTH_HEADER="Bearer your-circleci-token" npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}" ``` Make it executable (`chmod +x circleci-remote-mcp.sh`), then reference it from your MCP config: ```json { "mcpServers": { "circleci-remote-mcp-server": { "command": "/full/path/to/circleci-remote-mcp.sh" } } } ``` #### Claude Code ```bash claude mcp add circleci-mcp-server \ -e AUTH_HEADER="Bearer your-circleci-token" \ -- npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}" ``` Omit `--header` and `AUTH_HEADER` when using a [shared-token server](#1-deploy-the-server). ### 3. Verify the deployment ```bash # Health check (no auth required) curl http://localhost:8000/ping # Should return 401 when REQUIRE_REQUEST_TOKEN=true and no token is sent curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' # Should return 200 with a valid Bearer token and MCP Accept headers curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer your-circleci-pat" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' ``` ## Demo
Watch it in action Example: "Find the latest failed pipeline on my branch and get logs" — see the [wiki](https://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide) for more examples. https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74
## Tool Details
config_helper Assists with CircleCI configuration tasks by providing guidance and validation. - Validates your `.circleci/config.yml` for syntax and semantic errors - Provides detailed validation results and configuration recommendations - Example: "Validate my CircleCI config"
download_usage_api_data Downloads usage data from the CircleCI Usage API for a given organization. Accepts flexible date input (e.g., "March 2025" or "last month"). Cloud-only feature. **Option 1:** Start a new export job by providing: - `orgId`, `startDate`, `endDate` (max 32 days), `outputDir` **Option 2:** Check/download an existing export job by providing: - `orgId`, `jobId`, `outputDir` Returns a CSV file with CircleCI usage data for the specified time frame. > [!NOTE] > Usage data can be fed into the `find_underused_resource_classes` tool for cost optimization analysis.
find_flaky_tests Identifies flaky tests in your CircleCI project by analyzing test execution history. Leverages the [flaky test detection feature](https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detection) in CircleCI. This tool can be used in three ways: 1. **Using Project Slug (Recommended):** - First use `list_followed_projects` to get your projects, then: - Example: "Get flaky tests for my-project" 2. **Using CircleCI Project URL:** - Example: "Find flaky tests in https://app.circleci.com/pipelines/github/org/repo" 3. **Using Local Project Context:** - Works from your local workspace by providing workspace root and git remote URL - Example: "Find flaky tests in my current project" Output modes: - **Text (default):** Returns flaky test details in text format - **File** (requires `FILE_OUTPUT_DIRECTORY` env var): Creates a directory with flaky test details
find_underused_resource_classes Analyzes a CircleCI usage data CSV file to find jobs with average or max CPU/RAM usage below a given threshold (default: 40%). Provide a CSV file obtained from `download_usage_api_data`. Returns a markdown list of underused jobs organized by project and workflow — useful for identifying cost optimization opportunities.
get_build_failure_logs Retrieves detailed failure logs from CircleCI builds. This tool can be used in three ways: 1. **Using Project Slug and Branch (Recommended):** - First use `list_followed_projects` to get your projects, then: - Example: "Get build failures for my-project on the main branch" 2. **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" 3. **Using Local Project Context:** - Works from your local workspace by providing workspace root, git remote URL, and 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
get_job_test_results Retrieves test metadata for CircleCI jobs, allowing you to analyze test results without leaving your IDE. This tool can be used in three ways: 1. **Using Project Slug and Branch (Recommended):** - Example: "Get test results for my-project on the main branch" 2. **Using CircleCI URL:** - 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` 3. **Using Local Project Context:** - Works from your local workspace by providing workspace root, git remote URL, and branch name The tool returns: - Summary of all tests (total, successful, failed) - Detailed info on failed tests: name, class, file, error message, duration - List of successful tests with timing - Filter by test result > [!NOTE] > Test metadata must be configured in your CircleCI config. See [Collect Test Data](https://circleci.com/docs/collect-test-data/) for setup instructions.
get_latest_pipeline_status Retrieves the status of the latest pipeline for a given branch. This tool can be used in three ways: 1. **Using Project Slug and Branch (Recommended):** - Example: "Get the status of the latest pipeline for my-project on the main branch" 2. **Using CircleCI Project URL:** - Example: "Get the status of the latest pipeline for https://app.circleci.com/pipelines/github/org/repo" 3. **Using Local Project Context:** - Works from your local workspace by providing workspace root, git remote URL, and branch name 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 ```
list_artifacts Retrieves the list of artifacts produced by a CircleCI job. This tool can be used in three ways: 1. **Using Project Slug and Branch (Recommended):** - First use `list_followed_projects` to get your projects, then: - Example: "List artifacts for my-project on the main branch" 2. **Using CircleCI URL:** - Job URL: `https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789` - Workflow URL: `https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def` - Pipeline URL: `https://app.circleci.com/pipelines/gh/organization/project/123` 3. **Using Local Project Context:** - Works from your local workspace by providing workspace root, git remote URL, and branch name Useful for: - Finding download URLs for build artifacts (binaries, reports, logs) - Checking what artifacts were produced by a pipeline run
list_component_versions Lists all versions for a specific CircleCI component in an environment. Includes deployment status, commit information, and timestamps. The tool will prompt you to select the component and environment if not provided. Useful for: - Identifying which version is currently live - Selecting target versions for rollback operations - Getting deployment details (pipeline, workflow, job)
list_followed_projects Lists all projects that the user is following on CircleCI. - Shows all projects you have access to with their `projectSlug` - Example: "List my CircleCI projects" Example output: ``` Projects followed: 1. my-project (projectSlug: gh/organization/my-project) 2. another-project (projectSlug: gh/organization/another-project) ``` > [!NOTE] > The `projectSlug` (not the project name) is required for many other CircleCI tools.
rerun_workflow Reruns a workflow from its start or from the failed job. Returns the ID of the newly-created workflow and a link to monitor it.
run_pipeline Triggers a pipeline to run. This tool can be used in three ways: 1. **Using Project Slug and Branch (Recommended):** - Example: "Run the pipeline for my-project on the main branch" 2. **Using CircleCI URL:** - Pipeline URL, Workflow URL, Job URL, or Project URL with branch - Example: "Run the pipeline for https://app.circleci.com/pipelines/github/org/repo/123" 3. **Using Local Project Context:** - Works from your local workspace by providing workspace root, git remote URL, and branch name The tool returns a link to monitor the pipeline execution.
run_rollback_pipeline Triggers a rollback for a CircleCI project. The tool interactively guides you through: 1. **Project Selection** — lists followed projects for you to choose from 2. **Environment Selection** — lists available environments (auto-selects if only one) 3. **Component Selection** — lists available components (auto-selects if only one) 4. **Version Selection** — displays available versions; you select the target for rollback 5. **Rollback Mode Detection** — checks if a rollback pipeline is configured 6. **Execute Rollback** — two options: - **Pipeline Rollback:** triggers the rollback pipeline - **Workflow Rerun:** reruns a previous workflow using its workflow ID 7. **Confirmation** — summarizes and confirms before execution
## Troubleshooting
Quick Fixes **Most common issues:** 1. **Clear package caches:** ```bash npx clear-npx-cache npm cache clean --force ``` 2. **Force latest version:** Add `@latest` to your config: ```json "args": ["-y", "@circleci/mcp-server-circleci@latest"] ``` 3. **Restart your IDE completely** (not just reload window)
Authentication Issues - **Invalid token errors:** Verify your `CIRCLECI_TOKEN` in [Personal API Tokens](https://app.circleci.com/settings/user/tokens) - **Permission errors:** Ensure the token has read access to your projects - **Environment variables not loading:** Test with `echo $CIRCLECI_TOKEN` (Mac/Linux) or `echo %CIRCLECI_TOKEN%` (Windows)
Connection and Network Issues - **Base URL:** Confirm `CIRCLECI_BASE_URL` is `https://circleci.com` - **Corporate networks:** Configure npm proxy settings if behind a firewall - **Firewall blocking:** Check if security software blocks package downloads
System Requirements - **Node.js version:** Ensure >= 18.0.0 with `node --version` - **Update Node.js:** Consider latest LTS if experiencing compatibility issues - **Package manager:** Verify npm/pnpm is working: `npm --version`
IDE-Specific Issues - **Config file location:** Double-check the path for your OS - **Syntax errors:** Validate JSON syntax in your config file - **Console logs:** Check the IDE developer console for specific errors - **Try a different IDE:** Test in another supported editor to isolate the issue
Process Issues **Hanging processes — kill existing MCP processes:** ```bash # Mac/Linux: pkill -f "mcp-server-circleci" # Windows: taskkill /f /im node.exe ``` **Port conflicts:** Restart your IDE if the connection seems blocked.
Advanced Debugging - **Test package directly:** `npx @circleci/mcp-server-circleci@latest --help` - **Verbose logging:** `DEBUG=* npx @circleci/mcp-server-circleci@latest` - **Docker fallback:** Try Docker installation if npx fails consistently **Still need help?** 1. Check [GitHub Issues](https://github.com/CircleCI-Public/mcp-server-circleci/issues) for similar problems 2. Include your OS, Node version, and IDE when reporting issues 3. Share relevant error messages from the IDE console
## Telemetry The server supports OpenTelemetry metrics for tracking tool usage. Metrics are exported unless you set `DISABLE_TELEMETRY=true`. On remote deployments, metrics use the same token as the request (per-user PAT or shared server PAT). | Metric | Description | |--------|-------------| | `circleci.mcp.tool.invocations` | Tool invocation count | | `circleci.mcp.tool.duration_ms` | Execution time in ms | | `circleci.mcp.tool.errors` | Error count | # 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 ``` ## Building Docker Container You can build the Docker container locally using: ```bash docker build -t circleci:mcp-server-circleci . ``` This will create a Docker image tagged as `circleci:mcp-server-circleci` that you can use with any MCP client. **Local stdio mode** (single developer, token on the client): ```bash docker run --rm -i \ -e CIRCLECI_TOKEN=your-circleci-token \ -e CIRCLECI_BASE_URL=https://circleci.com \ circleci/mcp-server-circleci ``` **Remote mode** (centralized server for a team): see [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). ## 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 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](https://github.com/circleci-public/mcp-server-circleci/blob/HEAD/CONTRIBUTING.md)