circleci

Manage CI/CD pipelines, debug failed builds, and optimize test suites directly from your AI tools and agents - no terminal required.

CommunityOnlineNo sign-inGlobalFreeRead-only

What it can do

  • Cancel Workflow: Cancel a running CircleCI workflow, given its UUID (a workflow id from list_workflows or get_workflow). Cancellation is asynchronous: a successful call means the request was accepted,
  • Download Usage Data: Export a CircleCI organization's usage data as downloadable CSV files. This is a two-phase, asynchronous tool. Phase 1 — start: call with org (an org slug like "gh/acme" or an org
  • Get Deploy Component: Fetch a single CircleCI deploy component by its UUID (a component id from list_deploy_components), returning its name and owning project ID.

What data it sees

Do you need an account

No: the server works without sign-in

Manage CI/CD pipelines, debug failed builds, and optimize test suites directly from your AI tools and agents - no terminal required. The CircleCI MCP Server is a remote server hosted by CircleCI that connects AI tools and agents directly to your CI/CD pipelines, giving you a conversational interface to the same pipeline, workflow, job, and artifact data you'd normally reach through the CircleCI CLI or dashboard.

How to connect

How to connect circleci to Claude

The server address to paste into Claude settings:

https://circleci--circleci.run.tools

  1. Open Claude (claude.ai or the desktop app).
  2. Go to Settings → Connectors.
  3. Click Add custom connector.
  4. Paste the server address copied below into Remote MCP server URL and click Add.
  5. In a chat, click + → Connectors and switch the new connector on.

Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

Authorization

After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

How to connect circleci to ChatGPT

The server address to paste into ChatGPT settings:

https://circleci--circleci.run.tools

  1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
  2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
  3. Open Settings → Connectors and click Create.
  4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
  5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
  6. In a new chat open + → Apps/Connectors and enable the connector.

OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

Authorization

On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

How to connect circleci to Cursor

The server address to paste into Cursor settings:

https://circleci--circleci.run.tools

Fastest: click Open in Cursor below and confirm the prompt.

Manually:

  1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
  2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
  3. Save the file. The server appears in the MCP list; authorize it there if asked.

Authorization

If the service needs sign-in, an authorize button appears next to the server in the MCP list.

Server tool list (22)

Raw names from tools/list. Only developers need these.

cancel_workflowCancel a running CircleCI workflow, given its UUID (a workflow id from list_workflows or get_workflow). Cancellation is asynchronous: a successful call means the request was accepted, not that the workflow has stopped yet.
download_usage_dataExport a CircleCI organization's usage data as downloadable CSV files. This is a two-phase, asynchronous tool. Phase 1 — start: call with org (an org slug like "gh/acme" or an org UUID), start_date, and end_date (both YYYY-MM-DD, a window of at most 31 days) and no export_id; it returns an export_id. Phase 2 — poll/download: call again with that export_id and the same org; once the export is ready it returns pre-signed download URLs (no auth needed), or asks you to try again in a minute while it is still being prepared. Optionally include shared_org_ids on Phase 1 to cover additional organizations.
get_deploy_componentFetch a single CircleCI deploy component by its UUID (a component id from list_deploy_components), returning its name and owning project ID.
get_deploy_environmentFetch a single CircleCI deploy environment by its UUID (an environment id from list_deploy_environments), returning its name and owning org ID.
get_jobFetch a single CircleCI job by its UUID (a job id from list_jobs), returning its phase, outcome, and per-step detail including each step's exit code — the signal for which step failed.
get_job_logsFetch the stdout/stderr of a CircleCI job's steps, given the job's UUID (a job id from list_jobs). When no step is named, the failed steps are read automatically — the fast path from a failing job to the output that explains it. Output is rendered to plain text (ANSI escapes stripped, progress-bar redraws collapsed) unless raw=true. Use tail_lines to keep only the final lines of each step (where errors surface), and execution to pick among a parallel job's executions.
get_orbFetch a registry orb's metadata and published version history — given the orb as "namespace/name" (e.g. "circleci/go") or an orb UUID. Returns the latest version, 30-day usage stats, categories, and the list of published (stable) versions: the signal for whether a version pinned in a config is stale and what to bump it to. Use get_orb_source to read a specific version's definition.
get_orb_sourceFetch the YAML source of an orb version referenced by a CircleCI config — given the orb as "namespace/name" optionally pinned to a version ("circleci/go@1.2.3", "@volatile" for latest, or a dev label "@dev:my-branch"); with no @version the latest published version is read. The source is the definition of the commands, jobs, executors, and parameters the config invokes — read it to learn how to call an orb correctly. Works only for registry orbs (namespace/name), not inline or URL orbs.
get_runFetch a single CircleCI run by its UUID (a run id from list_runs), returning its phase, outcome, VCS details, and any config errors. The next step in the CI-access chain: a run's id feeds list_workflows.
get_workflowFetch a single CircleCI workflow by its UUID (a workflow id from list_workflows), returning its name, phase, and outcome. A workflow's id feeds list_jobs.
list_artifactsList the artifacts a CircleCI job produced — the files it persisted beyond the run, such as test reports, coverage, build outputs, or logs — given the job's UUID (a job id from list_jobs or get_job). Each artifact carries its path within the job and a URL to download it.
list_deploy_component_versionsList versions of a CircleCI deploy component — given the component's UUID (a component id from list_deploy_components or get_deploy_component). Optionally filter by deploy environment with the environment parameter.
list_deploy_componentsList CircleCI deploy components for a project — given its slug ("gh/org/repo") or UUID. Deploy components are the deployable units of a project (services, applications, libraries). Each component's id feeds get_deploy_component and list_deploy_component_versions.
list_deploy_environmentsList CircleCI deploy environments for an organization — given its slug ("gh/myorg") or UUID. Deploy environments represent named targets such as production or staging where components are released. Each environment's id feeds get_deploy_environment and can filter list_deploy_component_versions.
list_deploymentsList recent CircleCI deployments for a project — given its slug ("gh/org/repo") or UUID. Returns deployments newest-first with component name, version, type, status, and timestamps. Use this to answer "what was last deployed" or "when was version X deployed" without first looking up component or environment IDs.
list_job_testsList a CircleCI job's test results, given the job's UUID (a job id from list_jobs or get_job). By default only failing tests are returned — the ones that explain a failure; set all=true to include passing and skipped tests. Narrow further with filter ("result=...", "name=...", "classname=..."). A job's full test set can be very large, so the number returned is capped by limit (defaults to 100); when more tests matched than were returned, truncated is true — narrow the filter or raise limit for the rest.
list_jobsList the jobs belonging to a CircleCI workflow, given the workflow's UUID (a workflow id from list_workflows or get_workflow). The next step in the CI-access chain: each job's id feeds get_job.
list_runsList CircleCI runs for a project — given its slug ("gh/org/repo") or UUID — or the authenticated user's own runs across all projects (mine=true). Optionally filter by git branch and/or pipeline status. This is the entry point of the CI-access tool chain; each run's id feeds get_run and the workflow/job tools.
list_workflowsList the workflows belonging to a CircleCI run, given the run's UUID (a run id from list_runs or get_run). The next step in the CI-access chain: each workflow's id feeds get_workflow and list_jobs.
meGet details of the authenticated CircleCI user. Use this when a request is about the user's own profile, or when information is missing to build other tool calls (for example the caller's id or login).
rerun_workflowRerun a CircleCI workflow, given its UUID (a workflow id from list_workflows or get_workflow). By default every job reruns from the start; set from_failed=true to rerun only the failed jobs and everything downstream of them, reusing the successful ones. A rerun creates a new workflow, whose id is returned to follow the new run.
validate_configValidate a CircleCI pipeline config by compiling it — the equivalent of the `circleci config validate` CLI command. Pass the raw config YAML (the contents of .circleci/config.yml) as config; the server expands orbs, resolves parameter expressions, and expands matrix jobs, returning valid=true on success or valid=false with the compilation errors on failure. Supply org (a slug like "gh/acme" or a UUID) whenever the config references anything org-scoped: private registry orbs, or URL orbs — any orb whose value is a URL rather than "namespace/name@version", which are gated by the org's URL orb allow-list. Without org, only public registry orbs resolve, so those references fail with errors like "not permitted by the organization's URL orb allow-list" or "orb not found" — these are false negatives from missing org context, NOT real config problems, so before reporting a config invalid, check whether it declares private or URL orbs and if so retry with org. set preview_next=true to preview upcoming, potentially breaking config changes; pass pipeline_parameters to resolve << pipeline.parameters.* >> expressions.