Skip to directory

About CircleCI MCP

CircleCI provides a hosted MCP server for build and workflow diagnosis, and a separate local MCP server built into its CLI for broader project administration and configuration tasks.

What you can use it for

  • Investigate failed runs, jobs, logs, and tests
  • Rerun or cancel workflows
  • Use the CLI MCP for CircleCI config, organization, orb, policy, runner, and deploy administration
Connection and setup
Hosting
both
Transport
Not documented
Endpoint
https://mcp.circleci.com/v1/mcp
Authentication
Hosted server: OAuth 2.0 in the MCP client, or a CircleCI personal API token if client OAuth is unavailable. CLI server: use `circleci auth login` or CIRCLE_TOKEN. The former standalone npx/Docker MCP is deprecated.

Requirements

  • CircleCI account with access to the relevant organization/projects
  • For hosted mode: MCP client supporting remote Streamable HTTP and OAuth, or personal API token
  • For CLI mode: CircleCI CLI installed and authenticated

Setup steps

  1. Recommended hosted setup: add https://mcp.circleci.com/v1/mcp as a remote MCP endpoint and complete CircleCI OAuth.
  2. For local CLI mode, install the CircleCI CLI and authenticate with circleci auth login or set CIRCLE_TOKEN; enable using `circleci mcp claude enable`, `circleci mcp cursor enable`, or `circleci mcp vscode enable`.
  3. Use the hosted server for CI run observation and curated actions; use CLI MCP for config authoring and broader administration.
  4. Remove the old standalone circleci-mcp-server config if present; CircleCI marks it deprecated.
  5. Verify with hello or list_runs before requesting workflow reruns or cancellation.
Tools 22+

Official changelog says the hosted server has 24 tools but names only 22; names listed here are those explicitly published. Current tools can change over time. Endpoint and tool availability are OAuth/user-permission scoped.

  • list_runs

    List CircleCI runs, including the authenticated user’s runs across projects.

    01
  • get_run

    Retrieve a run and its outcome and source details.

    02
  • list_run_workflows

    List workflows belonging to a run.

    03
  • get_workflow

    Retrieve workflow status and details.

    04
  • list_workflow_jobs

    List jobs belonging to a workflow.

    05
  • get_job

    Retrieve job status, failed step and exit code.

    06
  • list_job_tests

    List test results for a job, including failing tests by default.

    07
  • get_job_logs

    Retrieve processed job-step logs, defaulting to failed steps.

    08
  • get_job_resource_usage

    Compare executor resource usage with its resource-class limits.

    09
  • list_job_artifacts

    List job artifacts with download URLs.

    10
  • rerun_workflow

    Rerun a workflow, optionally starting from failed jobs.

    11
  • cancel_workflow

    Cancel a running workflow.

    12
  • validate_config

    Compile and validate CircleCI configuration, expanding orbs and parameters.

    13
  • get_orb

    Inspect an orb and whether its pin is current.

    14
  • get_orb_source

    Retrieve orb source and usage guidance.

    15
  • list_deployments

    List project deployments and determine what is live.

    16
  • list_deploy_components

    List deployment components.

    17
  • list_deploy_environments

    List deployment environments.

    18
  • list_deploy_component_versions

    List versions of a deployment component.

    19
  • rollback_deploy_component

    Roll back a deployment component to a prior version.

    20
  • get_me

    Retrieve information about the authenticated CircleCI account.

    21
  • download_usage_data

    Download organization usage data for a date range.

    22

This server’s available tools can vary by account, permissions, or configuration. The list shown is not its full runtime catalog.

Limitations and notes
  • Rerunning and canceling workflows change external CI state; review before execution.
  • Hosted and CLI servers are separate implementations with different tool scopes and authentication flows.
  • The older standalone npx/Docker MCP server is deprecated; the publisher recommends hosted or CLI MCP.
  • Hosted user visibility depends on CircleCI organization/project permissions.
  • No runtime connection test performed.
Source discrepancies
  • Discovery entry points to the legacy standalone repository, while current CircleCI guidance recommends its hosted server or CLI-integrated MCP. Record describes current official options and explicitly flags legacy repo deprecation.
Original sources
  • official documentation

    The hosted endpoint is https://mcp.circleci.com/v1/mcp with OAuth2; the old standalone local server is deprecated. The current official changelog says 24 tools but explicitly names 22. Replaced the stale 13-tool overview list with the 22 identifiers spelled out in the changelog and retained partial status until the hosted tools/list response or a complete reference resolves the two unnamed tools.

  • official tool reference

    The hosted endpoint is https://mcp.circleci.com/v1/mcp with OAuth2; the old standalone local server is deprecated. The current official changelog says 24 tools but explicitly names 22. Replaced the stale 13-tool overview list with the 22 identifiers spelled out in the changelog and retained partial status until the hosted tools/list response or a complete reference resolves the two unnamed tools.

  • official tool reference

    The hosted endpoint is https://mcp.circleci.com/v1/mcp with OAuth2; the old standalone local server is deprecated. The current official changelog says 24 tools but explicitly names 22. Replaced the stale 13-tool overview list with the 22 identifiers spelled out in the changelog and retained partial status until the hosted tools/list response or a complete reference resolves the two unnamed tools.

Documentation checked 2026-10-28T13:19:36Z. Connection has not been runtime tested.

Similar tools