Bridge CircleCI

Bridge Claude Code to CircleCI for pipeline monitoring, build management, and deployment orchestration directly from your development environment through MCP.

When to Use This MCP Server

Connect this server when you need to:

• Monitor CircleCI build status, view job logs, and diagnose pipeline failures without leaving Claude Code to open the CircleCI dashboard
• Trigger new pipeline runs, approve manual gates, and manage deployment workflows as part of your development cycle
• Access CircleCI project insights including build duration trends, flaky test patterns, and pipeline success rates for optimization

Consider alternatives when:

• You use GitHub Actions, GitLab CI, or another CI/CD platform instead of CircleCI, where platform-specific integrations are more appropriate
• You need to modify CircleCI configuration files (.circleci/config.yml), which is a standard file editing task not requiring the API

Quick Start

Configuration

Copy
name: bridge-circleci
type: mcp
category: devtools

Example Connection

Copy
claude mcp:connect bridge-circleci

Available Tools

list-pipelines:     List recent pipelines for a project with status and trigger info
get-job-logs:       Retrieve output logs from a specific CircleCI job for debugging
trigger-pipeline:   Start a new pipeline run for a project with optional parameters
approve-job:        Approve a manual approval gate to continue a workflow
get-insights:       Access build duration, success rate, and credit usage metrics

Core Concepts

CircleCI MCP Integration Overview

Aspect	Details
Transport	stdio-based process via npx running @circleci/mcp-server-circleci
Authentication	CircleCI personal API token for accessing project and pipeline data
Scope	Full access to pipelines, workflows, jobs, artifacts, and insights
Base URL	Configurable for CircleCI Cloud (circleci.com) or self-hosted Server
Real-time	Poll-based status checks for pipeline and job progress monitoring

CircleCI Pipeline Architecture

Claude Code IDE
    |
    v
[MCP Client] --stdio--> [CircleCI MCP Server]
                              |
                              v
                     [CircleCI REST API v2]
                              |
                    +---------+---------+
                    |         |         |
                    v         v         v
              [Pipelines] [Workflows] [Jobs]
                    |         |         |
                    v         v         v
              [Triggers]  [Approvals] [Logs &
                                    Artifacts]

Configuration

Parameter	Type	Default	Description
CIRCLECI_TOKEN	string	required	Personal API token generated from CircleCI user settings
CIRCLECI_BASE_URL	string	https://circleci.com	Base URL for CircleCI API; change for self-hosted installations
default_project	string	none	Default project slug (gh/org/repo) to scope operations
poll_interval	integer	10000	Milliseconds between status checks when monitoring a running pipeline
max_log_lines	integer	500	Maximum number of log lines to retrieve from job output

Best Practices

1. Monitor Pipelines After Pushing Code - After pushing commits, use list-pipelines to watch the triggered pipeline progress. Quick access to build status and failure logs in Claude Code reduces the feedback loop compared to checking the web interface.

2. Use Insights for Pipeline Optimization - Regularly review get-insights data to identify slow jobs, frequently failing tests, and resource-intensive steps. This data helps prioritize optimization efforts where they have the most impact.

3. Scope Operations to Specific Projects - Set default_project to your current repository's CircleCI project slug. This prevents accidentally triggering pipelines or viewing logs from unrelated projects in multi-project organizations.

4. Keep API Tokens Scoped and Rotated - Generate CircleCI API tokens with the minimum necessary scope and rotate them regularly. Store the token in an environment variable rather than directly in MCP configuration files.

5. Review Job Logs for Flaky Tests - When a pipeline fails intermittently, use get-job-logs to compare output between passing and failing runs. Flaky test patterns often reveal timing issues, resource contention, or external dependency instability.

Common Issues

1. Token Authentication Returns 401 - Verify the CircleCI token has not expired or been revoked. Regenerate the token from CircleCI user settings and update the CIRCLECI_TOKEN environment variable.

2. Pipeline Not Found for Repository - Ensure the project slug follows the correct format: gh/organization/repository for GitHub, or bb/organization/repository for Bitbucket. The project must be set up in CircleCI before pipelines are accessible.

3. Job Logs Truncated or Missing - Very long job outputs may exceed the max_log_lines limit. Increase the limit or use the CircleCI web interface for jobs with extensive output. Some job types may not produce logs until they complete.