This profile is part of our MCP server directory, within The MCP Guide. Profiles are checked against each vendor's own documentation. Need a server built? See MCP development.
The CircleCI MCP server lets an AI agent read failed job logs, list test results, check runs and rerun or cancel workflows on CircleCI. CircleCI now hosts it at https://mcp.circleci.com/v1/mcp. Its older npm package, @circleci/mcp-server-circleci, is deprecated.
Checked against: CircleCI MCP overview and Connecting to the hosted CircleCI MCP server on 28 October 2026. eSEOspace did not install or test this server.
Key Takeaways
- CircleCI hosts the server at
https://mcp.circleci.com/v1/mcp, so there is nothing to install locally. - The hosted server lists 13 tools, from
get_job_logsandlist_job_teststorerun_workflowandcancel_workflow. - It signs in with OAuth2 (recommended) or a CircleCI personal API token as a bearer token.
- A second option, the CircleCI CLI MCP, runs locally and exposes the whole CircleCI CLI as tools.
- The old npm package is deprecated. CircleCI says to remove it before connecting to the hosted server.
At a glance
| Item | Detail |
|---|---|
| Publisher | CircleCI |
| Official? | Yes |
| Hosting | Hosted by CircleCI; CircleCI CLI MCP runs locally |
| Transport | Streamable HTTP (hosted); stdio or HTTP (CLI MCP) |
| Sign-in | OAuth2, or a personal API token as a bearer token |
| Read or write | Read and write (can rerun and cancel workflows) |
| Price | No separate MCP price in CircleCI's MCP docs |
| Source code | Hosted server: not published. Deprecated npm package: CircleCI-Public/mcp-server-circleci (Apache 2.0) |
| Status | Hosted server current; npm package deprecated |
What it can do
The tool table on CircleCI's MCP overview page:
| Tool | What it does |
|---|---|
hello | Verify the connection to the hosted server |
list_runs | List runs for a project, or your own runs across projects |
get_run | Fetch one run's phase, outcome, VCS details and config errors |
list_workflows | List the workflows in a run |
get_workflow | Fetch one workflow's name, phase and outcome |
rerun_workflow | Rerun a workflow, or only the failed jobs with from_failed |
cancel_workflow | Cancel a running workflow |
list_jobs | List the jobs in a workflow |
get_job | Fetch one job, with per-step exit codes |
get_job_logs | Fetch step output, reading failed steps by default |
list_artifacts | List files a job persisted |
list_job_tests | List a job's test results, failing tests by default |
download_usage_data | Export org usage data as CSV, up to 31 days at a time |
rerun_workflow and cancel_workflow change real CI state. CircleCI advises you to review these actions before confirming, especially on production-facing projects.
The CircleCI CLI MCP covers more ground. CircleCI says it exposes the entire CLI, including config validation, contexts and environment variables, orbs, policies, runners and Docker Layer Cache purges.
How to connect it
For Claude Code, CircleCI's docs give:
claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcpThen run /mcp, pick circleci-mcp-server and select Authenticate to sign in with OAuth2 in your browser. CircleCI is also listed in the Claude Connectors Directory and the Cursor MCP Marketplace, so you can add it there without a config file. The docs include setup for VS Code and Windsurf (now Devin Desktop) too.
If your client cannot complete OAuth2, or for headless use, send a CircleCI personal API token as Authorization: Bearer <token>. CircleCI says to treat the token like a password and keep it in an environment variable or secret store.
For the local CLI MCP, install the CircleCI CLI, run circleci auth login, then circleci mcp claude enable (or cursor or vscode). See Connecting to the CircleCI CLI MCP.
The deprecated npm package
The GitHub README now says "This package is deprecated." It gets no feature work, and the repository "will be archived." Old versions stay on npm, but CircleCI says running an unmaintained server that holds a personal API token "is not recommended." If you used its self-managed remote mode, CircleCI says to migrate first, because the hosted server is its direct replacement. To remove the old server in Claude Code, CircleCI gives claude mcp remove circleci-mcp-server.
Security notes
- Prefer OAuth2. CircleCI recommends it: there is no token to copy or store, and access can be revoked without changing your config.
- Guard write tools. Keep approvals on for
rerun_workflowandcancel_workflow. - Pick the right server. CircleCI suggests the CLI MCP when your organization keeps credentials on the developer's machine rather than sending them to a remote server.
- Retire the old package. Do not keep a deprecated server holding a long-lived token.
The MCP project's security best practices also cover risks such as token passthrough, confused deputy attacks and scope minimization.
Prefer per-user sign-in over one shared token. Read exposed local MCP servers and DNS rebinding, and visit the MCP Security Center.
Alternatives
- Buildkite MCP server, which has a hosted OAuth option and a read-only endpoint.
- GitHub MCP Server for GitHub Actions through its
actionstoolset. - GitLab MCP server for GitLab CI pipelines.
Next step
Connect the hosted server with OAuth2, and ask your client to confirm before rerun_workflow or cancel_workflow. Our guide on how to choose MCP servers helps you set rules, and the MCP server directory lists more tools.
Frequently asked questions
Is the CircleCI MCP server free?
CircleCI's MCP docs do not list a separate MCP price. You use your own CircleCI account. The deprecated npm package was open source under Apache 2.0.
Does CircleCI host the MCP server for me?
Yes. The hosted server is at https://mcp.circleci.com/v1/mcp, and CircleCI runs it. The CircleCI CLI MCP is the local alternative.
Should I still use @circleci/mcp-server-circleci?
No. CircleCI marks the npm package deprecated and says to move to the hosted server or the CLI MCP. Remove the old server before connecting the new one.
Can the AI trigger deployments?
The hosted server can rerun or cancel workflows, which may deploy depending on your config. It does not list a trigger-pipeline or rollback tool. Keep tool approvals on.
How do I share CircleCI MCP access across a team safely?
Have each developer connect to the hosted server with their own OAuth2 sign-in. That replaces the old self-managed remote mode, which CircleCI says to migrate off first.
