CircleCI MCP Server

MCP Server Configuration

Add to .claude/settings.json:

Copy
{
  "mcpServers": {
    "circleci": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "${CIRCLECI_TOKEN}"
      }
    }
  }
}

Available Tools

Tool	Description
get-pipeline-status	Check the status of a pipeline by ID or project
get-build-logs	Retrieve logs for a specific job/step
get-test-results	Get test results with failure details
rerun-workflow	Rerun a failed workflow (full or from-failed)
list-pipelines	List recent pipelines for a project
get-config	Retrieve the processed CircleCI config for a pipeline
get-artifacts	Download build artifacts from a job

Common Workflows

Diagnose Build Failure

1. list-pipelines → find the failing pipeline
2. get-pipeline-status → identify which job failed
3. get-build-logs → read the failure output
4. Analyze the error and suggest a fix
5. After fix is committed, rerun-workflow from-failed

Test Failure Analysis

1. get-test-results → get all failing test names and messages
2. Cross-reference with local code to identify the root cause
3. Suggest specific code fixes
4. Verify fix locally, then push and monitor pipeline

CircleCI Config Best Practices

Copy
# .circleci/config.yml
version: 2.1

orbs:
  node: circleci/[email protected]
  docker: circleci/[email protected]

jobs:
  test:
    docker:
      - image: cimg/node:20.11
      - image: cimg/postgres:16.2  # Service container
        environment:
          POSTGRES_DB: test_db
          POSTGRES_PASSWORD: test
    resource_class: medium
    steps:
      - checkout
      - node/install-packages:
          cache-path: node_modules
          pkg-manager: npm
      - run:
          name: Run tests
          command: npm test -- --ci --coverage
      - store_test_results:
          path: test-results  # Required for test insights
      - store_artifacts:
          path: coverage

  build:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - node/install-packages
      - run: npm run build
      - persist_to_workspace:
          root: .
          paths: [dist]

workflows:
  build-and-test:
    jobs:
      - test
      - build:
          requires: [test]
      - deploy:
          requires: [build]
          filters:
            branches:
              only: main

Common Failure Patterns & Fixes

Error Pattern	Likely Cause	Fix
ENOMEM / OOM killed	Insufficient memory	Upgrade resource_class to large
npm ERR! cache	Corrupted cache	Clear cache: add - run: npm cache clean --force
ETIMEOUT on install	Network issues	Add retry logic or use orb with built-in retry
Flaky test failures	Non-deterministic tests	Run with --retry 2, fix test isolation
Docker pull rate limit	Docker Hub limits	Use docker/docker-login orb with credentials

Setup

1. Generate a CircleCI personal API token at https://app.circleci.com/settings/user/tokens
2. Set the environment variable:

   Copy
   export CIRCLECI_TOKEN="your-token-here"

3. Add the MCP configuration to .claude/settings.json

Security Notes

• The CircleCI token grants access to all projects you have access to -- use project-scoped tokens when possible
• Build logs may contain sensitive environment variables -- review before sharing
• The MCP server only reads data and reruns workflows -- it cannot modify your config or settings
• Store the token in your shell profile or a secrets manager, never in version control