MCP Server Circleci

What CircleCI/mcp-server-circleci does

CircleCI/mcp-server-circleci connects MCP-compatible clients to CircleCI. Its tools cover CI troubleshooting, pipeline control, test and artifact inspection, configuration review, deployment version lookup, rollback workflows, and usage analysis.

For diagnostics, agents can retrieve build failure logs, inspect job test results, find flaky tests, check the latest pipeline state, and list artifacts. Configuration analysis accepts the complete CircleCI YAML content and returns validation errors or guidance. Pipeline operations can start a pipeline, rerun a workflow from the beginning or from its failed job, and trigger rollback procedures when the project has the required rollback setup.

The server also lists followed projects and component versions. Usage-related tools download organization usage data as a CSV and identify jobs whose CPU or RAM resource classes are below a selected utilization threshold.

How it works

The local server communicates with an MCP client through stdio. CircleCI operations authenticate with a personal API token. Most project-oriented tools accept exactly one of three identification approaches: a project slug with a branch, a CircleCI URL supplied by the user, or workspace root, Git remote URL, and branch information. Workflow reruns instead accept a workflow ID or workflow URL.

A common sequence starts with list_followed_projects, then uses the returned project slug for a status check, log lookup, test query, or pipeline action. Tools that select component versions can require several calls: first choose an environment, then a component, and finally a version. Pipeline triggering may also require a second call when a project exposes multiple pipeline definitions.

Large log and test responses can be truncated. The tool output includes an MCP truncation marker when this happens, and agents are instructed to acknowledge the warning before analyzing the remaining data. Full build logs can be written to an explicit output directory.

Setup and configuration

The package can be launched with NPX or Docker. NPX installation requires a supported Node.js release in the documented ranges and pnpm. Docker is an alternative for local deployments. A CircleCI personal API token is required and is passed through CIRCLECI_TOKEN.

Example NPX configuration:

{
  "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 for CircleCI cloud and is intended for on-premises customers. MAX_MCP_OUTPUT_LENGTH sets the maximum MCP response length and defaults to 50,000. Cursor, VS Code, and Claude Desktop configuration examples are included for both NPX and Docker.

Limitations and notes

This package is deprecated, no longer receives feature work, and is intended to be replaced by CircleCI’s hosted MCP server or CircleCI CLI MCP. The repository is scheduled for archival, although existing npm versions remain installable. Operating the self-managed remote transport requires special care because it brokers an organization’s CircleCI token; CircleCI’s hosted service is the direct replacement for that mode.

Tool calls require complete parameter sets and should not guess project slugs or URLs. URLs used as inputs must come from the user. Rollback actions depend on project-specific rollback pipeline configuration, deployment markers, component versions, and explicit confirmation. Usage CSV analysis also requires an absolute file path and the expected utilization columns.