CircleCI MCP Server

A project-agnostic MCP server over the CircleCI API, for inspecting pipelines, jobs, test results and logs from an AI assistant.

Read-only. It cannot trigger, rerun, cancel or modify anything in CircleCI.

Interim tool. CircleCI's own hosted MCP server (https://mcp.circleci.com/v1/mcp) is the long-term answer, but it must be added as a custom connector by a Claude org Owner/Admin, which not everyone can do. Use this until that's available to your team.

Install (teammates start here)

Requirements: Node.js 18+. No npm dependencies — it uses Node's built-in modules, so there is nothing to download at install time.

1. Install the package globally. Your team lead will give you a .tgz:

npm install -g ./iscqaautomation-circleci-mcp-server-2.3.0.tgz

This puts a circleci-mcp-server command on your PATH. Confirm it landed:

circleci-mcp-server --version

2. Create a CircleCI personal API token at https://app.circleci.com/settings/user/tokens — read access is all it needs.

3. Save the token where it survives package upgrades:

mkdir -p ~/.circleci-mcp && printf 'CIRCLECI_API_TOKEN=%s\n' 'PASTE_YOUR_TOKEN' > ~/.circleci-mcp/.env && chmod 600 ~/.circleci-mcp/.env

4. Verify before touching any client config. This is the step that saves an afternoon — a broken connector shows up in Claude only as one that silently fails to start.

circleci-mcp-server --check

Expect Authenticated as <you>, your projects listed, and 15 tools available.

5. Add it to your global Claude config, once, and it works in every project:

{
  "mcpServers": {
    "circleci": {
      "command": "circleci-mcp-server"
    }
  }
}

No absolute paths and no secrets in the config. Fully quit and reopen your client afterwards — closing the window is not enough.

Where the token can live

Checked in this order; the first hit wins, and a value already in the real environment always beats a file.

| Source | When to use it | |---|---| | The client's env block | Overriding the token on one machine | | $CIRCLECI_MCP_ENV_FILE | A path you choose, for unusual setups | | ~/.circleci-mcp/.env | The normal choice. Survives npm install -g upgrades | | <package dir>/.env | Back-compat with the old single-file layout |

The working directory is deliberately not searched — an MCP server is spawned with an unpredictable cwd, so reading ./.env would make your token depend on wherever the client happened to launch it.

Never commit your token. If one ever lands in source, a backup file, a ticket or a chat, revoke it and issue a new one — it can read every project your CircleCI account can see.

Configuring projects

Projects are referred to by short aliases so nobody has to remember full slugs. Crucially, each alias records the branch that suite actually runs on — a nightly suite running on develop is invisible to any tool that assumes the default branch.

Built-in defaults (ISC/MLA):

| Alias | CircleCI project | Branch | Teams channel | |---|---|---|---| | nlis-web | bitbucket/integritysystemscompany/nlis-playwright-tests | master | NLIS_Web_CI | | envd-web | bitbucket/integritysystemscompany/envd-web-playwright-tests | master | eNVD_Web_CI | | envd-api | bitbucket/integritysystemscompany/envd-api-tests | master | eNVD_Apis_CI | | envd-mobile | bitbucket/integritysystemscompany/envd-mobile-appium-tests | develop | eNVD_Mobile_CI |

Override for a different team or org with CIRCLECI_PROJECTS — note this replaces the defaults entirely, so list every project you need:

"env": {
  "CIRCLECI_PROJECTS": "{\"my-app\":{\"slug\":\"github/acme/my-app\",\"branch\":\"main\"}}"
}

Run circleci-mcp-server --check to see which registry is actually active.

Every project-scoped tool accepts any one of:

• project — a registered alias ("envd-mobile")
• project_slug — a full slug ("bitbucket/org/repo")
• cwd — path to a local git checkout; the slug is read from its remote

Plus optional branch (overrides the registered default) and all_branches: true (scan everything).

CLI

| Command | Purpose | |---|---| | circleci-mcp-server | Run the MCP server on stdio — what Claude invokes | | circleci-mcp-server --check | Verify the token, list active projects. Exits non-zero on failure | | circleci-mcp-server --tools | List the tool names | | circleci-mcp-server --version | Print the version | | circleci-mcp-server --help | Usage and every environment variable |

Tools

Start here

| Tool | Purpose | |---|---| | list_known_projects | Show configured aliases, slugs, branches; confirms the token is loaded | | get_ci_health_summary | All projects in one call — pass/fail plus failing tests. The daily review. |

Diagnosing a failure

| Tool | Purpose | |---|---| | get_latest_failed_tests | Every failed test across recent pipelines | | get_latest_pipeline_result | Latest pipeline: status, workflows, jobs, failures | | get_job_logs | Real console output — error text, stack traces, exit codes | | get_artifact_content | Read a report/JSON/log artifact's actual contents | | get_test_results | All test results for one job | | get_artifacts | List artifacts published by a job |

Is it flaky or genuinely broken?

| Tool | Purpose | |---|---| | get_test_history | One test's pass/fail timeline: when it last passed, when it broke, current streak | | get_flaky_test_analysis | Rank tests by failure rate with a flaky-vs-broken verdict |

Navigation / escape hatch

| Tool | Purpose | |---|---| | get_pipeline_runs | Recent pipelines for a project | | get_pipeline_workflows | Workflows for a pipeline (by number or UUID) | | get_workflow_jobs | Jobs in a workflow | | get_job_details | Details of one job | | api_probe | Read-only GET on any API v2 path, for anything not covered above |

Typical workflow

1. get_ci_health_summary                 → which projects are red?
2. get_latest_failed_tests(project=...)  → which tests failed, and why
3. get_job_logs(job_number=...)          → if the job died before tests ran
4. get_test_history(test_name=...)       → new break or long-standing?

get_job_logs matters most when there are no test results. If a job fails during checkout, dependency install, or emulator/Appium startup, the suite never runs and there is no test metadata to read — the logs are the only source of the actual error.

Troubleshooting

| Symptom | Cause | |---|---| | circleci-mcp-server: command not found | Global npm bin dir isn't on PATH. Check npm bin -g, or use the absolute path from npm ls -g | | No CircleCI API token found | No token in the client env block or ~/.circleci-mcp/.env. Run --check to see which files were read | | 401 ... token is missing, expired, or revoked | Token is wrong or has been revoked — issue a new one | | 404 ... check the project slug | Wrong slug, or the token's account can't see that project | | Connector won't start in Claude | Run circleci-mcp-server --check in a terminal first. Then confirm you fully quit and reopened the client | | Token vanished after an upgrade | It was in the package directory. Move it to ~/.circleci-mcp/.env | | Reports success but you know it failed | Check the branch — a suite on develop won't show up in a master-scoped scan. Use branch or all_branches: true | | No test metadata for this job | Job failed before tests ran, or the suite doesn't store_test_results. Use get_job_logs |

Maintaining and re-cutting the package

npm test                    # protocol handshake + tool surface, no token needed
npm version patch|minor     # bumps package.json; the server reads its version from it
npm pack                    # produces the .tgz to hand out

npm pack uses the files allowlist in package.json, so only five files ship and .env can never be among them. Confirm before distributing:

tar -tzf iscqaautomation-circleci-mcp-server-*.tgz

Not currently published to any registry — distribution is by tarball. To publish later, npm publish sends it to npmjs.org as a restricted scoped package; consider stripping the built-in ISC/MLA slugs first if it is ever made public.

Notes for maintainers

Non-obvious things worth preserving if you modify this:

• Workflows are fetched by pipeline UUID (/pipeline/{id}/workflow), not by project + pipeline number. The project-scoped form returns 404. An earlier version used it and silently skipped every pipeline, reporting real failures as "0 failed" — hence the loud error handling now.
• The pipeline endpoint ignores limit. It pages 20 at a time via next_page_token; limits are applied client-side after paging.
• Non-2xx responses raise. They are never parsed as data, so an auth or path error can't masquerade as an empty-but-successful result.
• Step logs need API v1.1. API v2 doesn't expose them.
• The token is only sent to circleci.com / circle-artifacts.com. Log and artifact URLs can redirect to pre-signed S3 links, which must not receive it.
• The cwd is never searched for a .env. See "Where the token can live".
• SERVER_VERSION is read from package.json so the version reported over MCP, by --version and on npm cannot drift apart.
• Log output is tail-truncated — errors and stack traces are at the end.

Version

2.3.0 — read-only; 15 tools; distributable npm package with a global circleci-mcp-server command.