mcp-server-circleci

Overview

The CircleCI MCP server provides a comprehensive bridge between CircleCI's CI/CD infrastructure and AI assistants like Cursor, Windsurf, Claude, and VS Code. It exposes 18 specialized tools for analyzing builds, finding flaky tests, rerunning workflows, managing artifacts, and optimizing resource usage. The server supports multiple deployment methods including NPX, Docker, and self-managed remote servers, with clear configuration instructions for each popular IDE and client.

Try asking AI

After installing, here are 5 things you can ask your AI assistant:

• analyze_diff

  Analyze git diffs against cursor rules for violations

  Try:Check my current git diff for any issuesTry:Analyze the diff against code quality rules
• config_helper

  Validate and get guidance for your CircleCI configuration

  Try:Check my CircleCI config for issuesTry:Help me optimize my .circleci/config.yml
• create_prompt_template

  Generate structured prompt templates for AI applications

  Try:Create a prompt template for user feedback analysisTry:Generate a template for code review
• download_usage_api_data

  Download usage data from the CircleCI Usage API

  Try:Get our CircleCI usage statisticsTry:Download pipeline usage data
• find_flaky_tests

  Identify flaky tests by analyzing test execution history

  Try:Find flaky tests in our projectTry:Which tests are inconsistent?
• find_underused_resource_classes

  Find jobs with underused compute resources

  Try:Find jobs that are wasting resourcesTry:Check for underutilized resource classes
• get_build_failure_logs

  Retrieve detailed failure logs from CircleCI builds

  Try:Get logs for the failed buildTry:Show me the error details from the last failed pipeline
• get_job_test_results

  Retrieve test metadata and results for CircleCI jobs

  Try:Get test results for the last buildTry:Show me the test coverage metrics
• get_latest_pipeline_status

  Get the status of the latest pipeline for a branch

  Try:Check the status of the main pipelineTry:Is my feature branch pipeline complete?
• list_artifacts

  List artifacts produced by a CircleCI job

  Try:Show me the build artifactsTry:List the deployment packages
• rerun_workflow

  Rerun a workflow from start or from the failed job

  Try:Rerun the failed workflowTry:Restart the pipeline from the failing step
• run_pipeline

  Trigger a pipeline to run

  Try:Run the pipeline for main branchTry:Trigger a build for my changes

Comparable tools

Installation

{
  "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"
      }
    }
  }
}

{
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

FAQ

What permissions do I need for the CircleCI API token?

The token needs the 'Status' and 'Settings' scopes to access pipeline information, build details, and configuration validation features.

Can I use this server with on-premise CircleCI?

Yes, you need to set the CIRCLECI_BASE_URL environment variable to your on-premise instance URL instead of the default 'https://circleci.com'.

Compare mcp-server-circleci with