Integrations
Integrates with CircleCI to retrieve build failure logs and identify flaky tests. Supports accessing logs via CircleCI URLs or local project context, and analyzing test execution history to detect unreliable tests in a project's test suite.
CircleCI MCP Server
Model Context Protocol (MCP) is a new, standardized protocol for managing context between large language models (LLMs) and external systems. In this repository, we provide an MCP Server for CircleCI.
This lets you use Cursor IDE, or any MCP Client, to use natural language to accomplish things with CircleCI, e.g.:
Find the latest failed pipeline on my branch and get logs
https://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide
https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74
Requirements
- pnpm package manager - Learn more
- Node.js >= v18.0.0
- CircleCI API token - you can generate one through the CircleCI. Learn more or click here for quick access.
Installation
Cursor
Add the following to your cursor MCP config:
See the guide below for more information on using MCP servers with cursor: https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers
VS Code
To install CircleCI MCP Server for VS Code in .vscode/mcp.json
See the guide below for more information on using MCP servers with VS Code: https://code.visualstudio.com/docs/copilot/chat/mcp-servers
Claude Desktop
Add the following to your claude_desktop_config.json:
To find/create this file, first open your claude desktop settings. Then click on "Developer" in the left-hand bar of the Settings pane, and then click on "Edit Config"
This will create a configuration file at:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
See the guide below for more information on using MCP servers with Claude Desktop: https://modelcontextprotocol.io/quickstart/user
Claude Code
After installing Claude Code, run the following command:
See the guide below for more information on using MCP servers with Claude Code: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp
Windsurf
Add the following to your windsurf mcp_config.json:
Installing via Smithery
To install CircleCI MCP Server for Claude Desktop automatically via Smithery:
See the guide below for more information on using MCP servers with windsurf: https://docs.windsurf.com/windsurf/mcp
Features
Supported Tools
get_build_failure_logs
Retrieves detailed failure logs from CircleCI builds. This tool can be used in two ways:- Using CircleCI URLs:
- Provide a failed job URL or pipeline URL directly
- Example: "Get logs from https://app.circleci.com/pipelines/github/org/repo/123"
- Using Local Project Context:
- Works from your local workspace by providing:
- Workspace root path
- Git remote URL
- Branch name
- Example: "Find the latest failed pipeline on my current branch"
- Works from your local workspace by providing:
The tool returns formatted logs including:
- Job names
- Step-by-step execution details
- Failure messages and context
This is particularly useful for:
- Debugging failed builds
- Analyzing test failures
- Investigating deployment issues
- Quick access to build logs without leaving your IDE
- Using CircleCI URLs:
find_flaky_tests
Identifies flaky tests in your CircleCI project by analyzing test execution history. This leverages the flaky test detection feature described here: https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detectionThis tool can be used in two ways:- Using CircleCI Project URL:
- Provide the project URL directly from CircleCI
- Example: "Find flaky tests in https://app.circleci.com/pipelines/github/org/repo"
- Using Local Project Context:
- Works from your local workspace by providing:
- Workspace root path
- Git remote URL
- Example: "Find flaky tests in my current project"
- Works from your local workspace by providing:
The tool returns detailed information about flaky tests, including:
- Test names and file locations
- Failure messages and contexts
This helps you:
- Identify unreliable tests in your test suite
- Get detailed context about test failures
- Make data-driven decisions about test improvements
- Using CircleCI Project URL:
get_latest_pipeline_status
Retrieves the status of the latest pipeline for a given branch. This tool can be used in two ways:- Using CircleCI Project URL:
- Provide the project URL directly from CircleCI
- Example: "Get the status of the latest pipeline for https://app.circleci.com/pipelines/github/org/repo"
- Using Local Project Context:
- Works from your local workspace by providing:
- Workspace root path
- Git remote URL
- Branch name
- Example: "Get the status of the latest pipeline for my current project"
- Works from your local workspace by providing:
The tool returns a formatted status of the latest pipeline:
- Workflow names and their current status
- Duration of each workflow
- Creation and completion timestamps
- Overall pipeline health
Example output:
CopyThis is particularly useful for:
- Checking the status of the latest pipeline
- Getting the status of the latest pipeline for a specific branch
- Quickly checking the status of the latest pipeline without leaving your IDE
- Using CircleCI Project URL:
get_job_test_results
Retrieves test metadata for CircleCI jobs, allowing you to analyze test results without leaving your IDE. This tool can be used in two ways:- Using CircleCI URL (Recommended):
- Provide a CircleCI URL in any of these formats:
- Example: "Get test results for https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def"
- Using Local Project Context:
- Works from your local workspace by providing:
- Workspace root path
- Git remote URL
- Branch name
- Example: "Get test results for my current project on the main branch"
- Works from your local workspace by providing:
The tool returns detailed test result information:
- Summary of all tests (total, successful, failed)
- Detailed information about failed tests including:
- Test name and class
- File location
- Error messages
- Runtime duration
- List of successful tests with timing information
This is particularly useful for:
- Quickly analyzing test failures without visiting the CircleCI web UI
- Identifying patterns in test failures
- Finding slow tests that might need optimization
- Checking test coverage across your project
- Troubleshooting flaky tests
Note: The tool requires that test metadata is properly configured in your CircleCI config. For more information on setting up test metadata collection, see: https://circleci.com/docs/collect-test-data/
- Using CircleCI URL (Recommended):
config_helper
Assists with CircleCI configuration tasks by providing guidance and validation. This tool helps you:- Validate CircleCI Config:
- Checks your .circleci/config.yml for syntax and semantic errors
- Example: "Validate my CircleCI config"
The tool provides:
- Detailed validation results
- Configuration recommendations
This helps you:
- Catch configuration errors before pushing
- Learn CircleCI configuration best practices
- Troubleshoot configuration issues
- Implement CircleCI features correctly
- Validate CircleCI Config:
create_prompt_template
Helps generate structured prompt templates for AI-enabled applications based on feature requirements. This tool:- Converts Feature Requirements to Structured Prompts:
- Transforms user requirements into optimized prompt templates
- Example: "Create a prompt template for generating bedtime stories by age and topic"
The tool provides:
- A structured prompt template
- A context schema defining required input parameters
This helps you:
- Create effective prompts for AI applications
- Standardize input parameters for consistent results
- Build robust AI-powered features
- Converts Feature Requirements to Structured Prompts:
recommend_prompt_template_tests
Generates test cases for prompt templates to ensure they produce expected results. This tool:- Provides Test Cases for Prompt Templates:
- Creates diverse test scenarios based on your prompt template and context schema
- Example: "Generate tests for my bedtime story prompt template"
The tool provides:
- An array of recommended test cases
- Various parameter combinations to test template robustness
This helps you:
- Validate prompt template functionality
- Ensure consistent AI responses across inputs
- Identify edge cases and potential issues
- Improve overall AI application quality
- Provides Test Cases for Prompt Templates:
Development
Getting Started
- Clone the repository:Copy
- Install dependencies:Copy
- Build the project:Copy
Development with MCP Inspector
The easiest way to iterate on the MCP Server is using the MCP inspector. You can learn more about the MCP inspector at https://modelcontextprotocol.io/docs/tools/inspector
- Start the development server:Copy
- In a separate terminal, launch the inspector:Copy
- Configure the environment:
- Add your
CIRCLECI_TOKEN
to the Environment Variables section in the inspector UI - The token needs read access to your CircleCI projects
- Optionally you can set your CircleCI Base URL. Defaults to
https//circleci.com
- Add your
Testing
- Run the test suite:Copy
- Run tests in watch mode during development:Copy
For more detailed contribution guidelines, see CONTRIBUTING.md
You must be authenticated.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
This MCP server lets you use Cursor IDE, or any MCP Client enabled agent, to use natural language to accomplish things with CircleCI, e.g: Find the latest failed pipeline on my branch and get logs
Related Resources
Related MCP Servers
- -securityFlicense-qualityAn MCP server that provides detailed information about your development environment to the Cursor code editor, enabling more context-aware assistance.Last updated -1Python
- AsecurityAlicenseAqualityAn MCP server integration that enables Cursor AI to communicate with Figma, allowing users to read designs and modify them programmatically through natural language commands.Last updated -195,1853,528JavaScriptMIT License
- AsecurityAlicenseAqualitySimple MCP Server to enable a human-in-the-loop workflow in tools like Cline and Cursor. This is especially useful for developing desktop applications that require complex user interactions to test.Last updated -113PythonMIT License
- -securityAlicense-qualityAn open-source MCP server that provides applications like Cursor, Windsurf, and Claude with access to llms.txt documentation files, allowing users to control and audit context retrieval.Last updated -4PythonMIT License