CircleCI MCP Server

The CircleCI MCP Server connects AI assistants such as Claude Code, Cursor, VS Code, or Windsurf to the CI/CD platform CircleCI. Anyone who runs builds and tests on CircleCI can ask the assistant questions like "Why did the last run on the main branch fail?", "Which tests failed in this job?", or "Run the workflow again" without switching to the web interface and copying logs by hand. The server is operated by CircleCI itself. According to the documentation it runs as a hosted service at https://mcp.circleci.com/v1/mcp, so nothing has to be installed or maintained locally.

What is the CircleCI MCP Server?

MCP, the Model Context Protocol, is an open protocol through which AI assistants call tools of external services. The hosted CircleCI server provides a deliberately compact set of tools that, according to the documentation, serves to observe CI runs and react to them in a targeted way. These include listing and retrieving runs (list_runs, get_run), showing workflows and jobs, reading job logs (get_job_logs), listing artifacts and test results, and rerunning or canceling a workflow. The assistant can additionally download usage data for the organization.

What is it particularly useful for?

The greatest benefit lies in troubleshooting. When a build fails, the assistant reads the logs of the affected steps itself, relates the error to the code you have open in the editor, and proposes a fix. That saves the detour through web interface, log output, and clipboard. Questions such as "Which runs on this branch were last green?" can also be answered in a single sentence. Compared with generic Git or shell servers, this server knows CircleCI concepts, that is pipelines, workflows, jobs, and tests, and therefore returns answers that fit your own pipeline directly.

Hosted server, CLI MCP, and the deprecated local server

According to the documentation, CircleCI distinguishes two variants. The hosted server focuses on operations, that is failure analysis, logs, and workflow control. The CLI MCP is built into the CircleCI CLI, runs locally, and covers a larger scope, such as authoring configuration, orb tooling, and policy management. The earlier npm package @circleci/mcp-server-circleci, by contrast, is deprecated: the repository states that it is no longer maintained and points to the hosted server. Remove older setups before you connect the hosted server.

Setup

For Claude Code, the documentation names the command claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp. Claude Desktop, claude.ai, and Cursor list CircleCI in their directories, where it is enough to add the entry and sign in. For VS Code and Windsurf you enter the URL in .vscode/mcp.json or mcp_config.json respectively. Sign-in preferably happens through OAuth2: most clients detect this and open the CircleCI sign-in on first connection. If a client cannot complete an OAuth2 flow, a personal API token as a bearer header is the fallback.

Security and limits

The assistant acts within the scope of your CircleCI account. Two of the tools, rerunning and canceling workflows, change the state of your pipelines; the documentation recommends reviewing such actions before confirming them on shared projects. Job logs can contain credentials or personal data and enter the AI client context and therefore reach the model provider. Prefer OAuth2 over long-lived tokens, and never store tokens in configuration files that end up in a repository.

Costs

According to the documentation, the hosted server is available on the Free, Performance, and Scale plans and supports all version control providers connected to CircleCI. An account with access to the projects is sufficient. Which terms apply to your builds is shown on CircleCI's official pricing page.

Who is the CircleCI MCP Server for?

It is worthwhile for development teams that already use CircleCI in production and frequently spend time on failed runs. Anyone using a different CI platform gains nothing from it, because the server is an access path to CircleCI and not a standalone tool.

A CircleCI account with access to the projects and an MCP client that supports remote servers over HTTP, such as Claude Code, Cursor, VS Code, or Windsurf.

With the CircleCI MCP Server, an AI assistant investigates failed pipelines, reads job logs, and reruns workflows. This guide leads from setup to the first failure analysis.

Step 1: Check the prerequisites

You need a CircleCI account with access to your projects and an MCP client that supports remote servers over HTTP. According to the documentation, the hosted server is available on the Free, Performance, and Scale plans, and you do not have to install anything locally.

Remove the old local server

The earlier package @circleci/mcp-server-circleci is deprecated and no longer maintained. Remove an existing entry from your client's MCP configuration before you connect the hosted server so that the two do not overlap.

Step 2: Set up in Claude Code

Add the server with claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp. On first connection the CircleCI sign-in opens; confirm the access.

claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp

Other clients

Claude Desktop, claude.ai, and Cursor list CircleCI in their directories: find the entry, add it, sign in. In VS Code you enter the URL https://mcp.circleci.com/v1/mcp in .vscode/mcp.json, in Windsurf in mcp_config.json.

Step 3: Token as a fallback

If your client cannot complete an OAuth2 flow, pass a personal API token as the header Authorization: Bearer <token>. Read it from an environment variable and do not store it in a file that ends up in a repository.

Step 4: First queries

Start with the connectivity check via the hello tool, then read-only: "Show the latest failed runs on the main branch." or "Read the logs of the failed job and explain the cause." Name the branch or run as precisely as possible.

Confirm interventions deliberately

Rerunning and canceling workflows changes the state of your pipelines. Review these actions on shared projects before you confirm them. Also keep in mind that logs enter the AI client context and can contain credentials.

OAuth2 with sign-in to the CircleCI account (recommended) or a personal API token as a bearer header if the client does not support an OAuth2 flow.

Access to runs, workflows, jobs, logs, artifacts, test results, and usage data of the account's projects as well as workflow control (rerun, cancel).

The server runs hosted by CircleCI. Logs and test results the assistant retrieves enter the AI client context and therefore reach the model provider.

Accidental cancellation or rerun of workflows, exposure of logs containing credentials or personal data to the model provider, and misuse of long-lived API tokens.