CircleCI

CircleCI

This connector works with CircleCI through the API v2 (https://circleci.com/api/v2): projects, pipelines, workflows and jobs, test results and artifacts, Insights metrics and flaky tests, contexts, and the names of environment variables. It can start pipelines and rerun or cancel workflows after you confirm. It acts as the user who owns the token and sees what that user can see.

Setup (about 2 minutes)

1. In CircleCI open User Settings > Personal API Tokens (https://app.circleci.com/settings/user/tokens) and click Create New Token.
2. Copy the token (newer ones start with CCIPAT_) and paste it into CIRCLECI_TOKEN. It is sent in the Circle-Token header to circleci.com only. Project API tokens do not work with API v2.
3. Check the setup with circleci_get_current_user, then circleci_list_collaborations.

The token has the same rights as your CircleCI user in every organization you belong to; share the MCP server only with people who may see those builds.

Project slugs: most tools need a project slug, shown in Project Settings > Overview:

• GitHub OAuth and Bitbucket Cloud projects: gh/<org>/<repo> or bb/<workspace>/<repo>, e.g. gh/acme/web-app.
• GitHub App and GitLab projects: circleci/<organization id>/<project id>, e.g. circleci/43G3lM5RtfFE7v5sa4nWAU/44n9wujWcTnVZ2b5S8Fnat. Pass the slug with its slashes as it is.

How to work

1. circleci_list_pipelines (newest first, optionally one branch), circleci_get_pipeline by id, or circleci_get_pipeline_by_number for the #number in the app.
2. circleci_list_pipeline_workflows (or circleci_get_workflow by id), then circleci_list_workflow_jobs to find the failed job and its job_number.
3. circleci_get_job, circleci_list_job_tests (counts, and failed tests with messages) and circleci_list_job_artifacts. Full step logs are only in the CircleCI app via the job's web_url.
4. Trends: circleci_get_workflow_metrics, circleci_get_workflow_summary and circleci_list_flaky_tests. Insights data is refreshed daily.
5. Configuration: circleci_get_project, circleci_list_contexts, circleci_list_context_env_var_names and circleci_list_project_env_var_names. Only names are returned, never values.

Writes always need the user's confirmation: circleci_trigger_pipeline (needs a definition id from circleci_list_pipeline_definitions, which needs the project id from circleci_get_project; not available for GitLab projects), circleci_rerun_workflow and circleci_cancel_workflow. Each uses credits or stops running work, and may run or interrupt deploy jobs. Describe the effect and call only after the user agrees. Nothing here deletes projects, contexts or variables.

Pagination: lists return next_page_token; call again with page_token set to it until it is empty.

Errors: 401 means the token is wrong or revoked (or a project token was used). 404 usually means a wrong project slug, or a project the user cannot see; CircleCI answers 404 rather than 403 for projects outside your access. 429 means the rate limit is reached; wait and retry.

Out of scope here: approving held jobs, creating or deleting projects, contexts, environment variables, schedules and webhooks, and reading full job step logs.