# CircleCI MCP Server

> Lets your agent find out why a CircleCI run failed, read job logs and failing tests, and rerun or cancel workflows from the chat.

CircleCI's own hosted MCP server connects your agent to your CircleCI runs, so you can diagnose build failures, read logs and act on workflows without leaving the chat.

What you can do with it
- List recent runs for a project, or your own runs across projects, filtered by branch or status
- Drill into a run's workflows, jobs and steps, with each step's exit code and any config errors
- Read a job's logs; when you don't name a step, it reads the failed ones
- See which tests failed in a job, and list the files it saved, such as test reports, coverage or build output
- Rerun a workflow from the start or only from its failed jobs, or cancel one that's running
- Export an organization's usage data as CSV files, up to 31 days at a time

How it connects
CircleCI hosts it at https://mcp.circleci.com/v1/mcp, and it's listed in Claude's connector directory and Cursor's MCP marketplace. Most agents ask you to sign in to CircleCI with OAuth the first time you connect. If yours can't, or for headless use, send a CircleCI personal API token as a bearer token in the Authorization header. CircleCI's guides cover Claude, Claude Code, Cursor, VS Code and Windsurf.

Good to know
- Rerunning or canceling a workflow changes real CI state, so check what your agent is about to do, especially on shared projects.
- For config authoring, orbs, contexts and other admin tasks, CircleCI points to the MCP server built into the CircleCI CLI instead. Its older npx-based local server is deprecated.
- When CircleCI adds tools, reconnect the server to load them.

- Type: Plugin
- Made by: Circleci
- Category: Cloud & DevOps
- Formats: Remote MCP
- Version: 1.0.0
- Website: https://circleci.com/docs/guides/toolkit/circleci-mcp-overview/
- Page: https://pluginboard.ai/plugins/circleci-mcp

## Works with

- ChatGPT
- Claude
- Muse
- Grok Bot
- Gemini
- Grok
- GitHub Copilot
- Cursor
- Claude Code
- Codex
- Antigravity
- Gemini CLI
- Replit
- OpenClaw
- OpenCode
- Hermes Agent

## Install

You'll need:

- `Authorization` (required): OAuth 2.0 Bearer token

Replace each `<NAME>` placeholder with your own value.

### ChatGPT

In ChatGPT on the web: Plugins → + → Add custom MCP server, then paste https://mcp.circleci.com/v1/mcp under Connection. Business and Enterprise plans; Pro can add read-only servers.

### Claude

In Claude (web or desktop): Customize → Connectors → Add custom connector, then paste https://mcp.circleci.com/v1/mcp

### Muse

In Muse: In a Muse chat, ask it to create a custom connector for the MCP server at https://mcp.circleci.com/v1/mcp. Then tap Connect on the card it shows and sign in, or add your key.

### Grok Bot

In Grok Bot: In a chat with your Bot, say "Add this MCP server: https://mcp.circleci.com/v1/mcp". It confirms the details with you and sets it up, and the tools are ready from your next message.

### Grok

In Grok on the web: At grok.com/connectors: New Connector → Custom, then enter https://mcp.circleci.com/v1/mcp and sign in if it asks.

### GitHub Copilot

Add to VS Code: vscode:mcp/install?%7B%22name%22%3A%22circleci-mcp-server%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.circleci.com%2Fv1%2Fmcp%22%7D

Copilot CLI:

```shell
copilot mcp add --transport http --header 'Authorization: <Authorization>' circleci-mcp-server https://mcp.circleci.com/v1/mcp
```

### Cursor

Add to Cursor: cursor://anysphere.cursor-deeplink/mcp/install?name=circleci-mcp-server&config=eyJ1cmwiOiJodHRwczovL21jcC5jaXJjbGVjaS5jb20vdjEvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiPEF1dGhvcml6YXRpb24%2BIn19

Add to .cursor/mcp.json:

```json
{
  "mcpServers": {
    "circleci-mcp-server": {
      "url": "https://mcp.circleci.com/v1/mcp",
      "headers": {
        "Authorization": "<Authorization>"
      }
    }
  }
}
```

### Claude Code

Run in your terminal:

```shell
claude mcp add --transport http --header 'Authorization: <Authorization>' circleci-mcp-server https://mcp.circleci.com/v1/mcp
```

### Codex

Run in your terminal:

```shell
codex mcp add circleci-mcp-server --url https://mcp.circleci.com/v1/mcp
```

### Antigravity

Add to ~/.gemini/config/mcp_config.json:

```json
{
  "mcpServers": {
    "circleci-mcp-server": {
      "url": "https://mcp.circleci.com/v1/mcp",
      "headers": {
        "Authorization": "<Authorization>"
      }
    }
  }
}
```

### Gemini CLI

Run in your terminal:

```shell
gemini mcp add --transport http --header 'Authorization: <Authorization>' circleci-mcp-server https://mcp.circleci.com/v1/mcp
```

### Replit

In Replit: At replit.com/integrations, open MCP Servers → + Add MCP server, paste https://mcp.circleci.com/v1/mcp (add any headers under Advanced settings), then click Test & save.

### OpenClaw

Run in your terminal:

```shell
openclaw mcp add circleci-mcp-server --url https://mcp.circleci.com/v1/mcp --transport streamable-http
```

If it needs a key or sign-in: For https://mcp.circleci.com/v1/mcp, add --header NAME=value for each header it needs, or --auth oauth and then run openclaw mcp login circleci-mcp-server.

### OpenCode

Run in your terminal:

```shell
opencode mcp add circleci-mcp-server --url https://mcp.circleci.com/v1/mcp
```

If it needs a key: For https://mcp.circleci.com/v1/mcp, add --header 'NAME=value' for each header it needs. Add --global to use it in every project.

### Hermes Agent

Run in your terminal:

```shell
hermes mcp add circleci-mcp-server --url https://mcp.circleci.com/v1/mcp
```

Add to ~/.hermes/config.yaml:

```json
{
  "mcp_servers": {
    "circleci-mcp-server": {
      "url": "https://mcp.circleci.com/v1/mcp",
      "headers": {
        "Authorization": "<Authorization>"
      }
    }
  }
}
```

If it signs in with OAuth: If https://mcp.circleci.com/v1/mcp asks you to sign in, add --auth oauth to the command, or auth: oauth to its entry.

---
From Pluginboard (https://pluginboard.ai).