CircleCI
A specialized server implementation for the Model Context Protocol (MCP) designed to integrate with CircleCI's development workflow. This project serves as a bridge between CircleCI's infrastructure and the Model Context Protocol, enabling enhanced A
What is CircleCI?
CircleCI is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to specialized server implementation for the model context protocol (mcp) designed to integrate with circleci's development workflow. this project serves as a bridge between circleci's infrastructure and...
A specialized server implementation for the Model Context Protocol (MCP) designed to integrate with CircleCI's development workflow. This project serves as a bridge between CircleCI's infrastructure and the Model Context Protocol, enabling enhanced A
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- get_build_failure_logs
- find_flaky_tests
- get_latest_pipeline_status
- get_job_test_results
- config_helper
Use Cases
Maintainer
Works with
Installation
NPM
npx -y @circleci/mcp-server-circleciManual Installation
npx -y @circleci/mcp-server-circleciConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use CircleCI
The CircleCI MCP Server is an official integration from CircleCI that gives AI assistants direct access to your CircleCI pipelines, builds, and test results through 18 purpose-built tools. It enables developers to diagnose build failures, identify flaky tests, run pipelines, and validate CI configuration files through natural language — all without leaving their AI assistant. Teams use it to dramatically reduce the time spent context-switching between their editor and the CircleCI dashboard.
Prerequisites
- A CircleCI account with at least one active project
- A CircleCI personal API token — generated at https://app.circleci.com/settings/user/tokens
- Node.js 18 or later (for npx installation)
- An MCP-compatible client such as Claude Desktop or Claude Code
Generate a CircleCI personal API token
Log in to CircleCI, navigate to User Settings > Personal API Tokens, and click 'Create New Token'. Give it a descriptive name like 'mcp-server' and copy the token value immediately — it is shown only once.
Add the server to Claude Code (recommended)
If you use Claude Code, add the CircleCI MCP server with one command, passing your token as an environment variable.
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latestOr configure Claude Desktop manually
Open your claude_desktop_config.json and add the CircleCI server entry under mcpServers. Set CIRCLECI_TOKEN to your personal API token. CIRCLECI_BASE_URL is optional and only needed for self-hosted CircleCI instances.
{
"mcpServers": {
"circleci": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci@latest"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-personal-api-token"
}
}
}
}Restart your MCP client
Quit and reopen Claude Desktop, or reload Claude Code, so the new server configuration is picked up. The server exposes 18 tools that will appear in Claude's available tool list.
Test the connection with a pipeline status check
Ask Claude to show the latest pipeline status for one of your projects. If the response includes real pipeline data, the server is working correctly.
CircleCI Examples
Client configuration
Claude Desktop JSON configuration for the CircleCI MCP server using a personal API token.
{
"mcpServers": {
"circleci": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci@latest"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-personal-api-token",
"CIRCLECI_BASE_URL": "https://circleci.com"
}
}
}
}Prompts to try
Example prompts that exercise the 18 tools exposed by the CircleCI MCP server.
- "Get the build failure logs for my-project on the main branch."
- "Find flaky tests in my current project over the last 30 days."
- "Show the latest pipeline status for the backend-api repository."
- "Validate my .circleci/config.yml file and suggest improvements."
- "Run the pipeline for my-project on the main branch."
- "List the test results from the most recent job on the feature/auth branch."Troubleshooting CircleCI
Authentication fails with '401 Unauthorized'
Verify that CIRCLECI_TOKEN is set to a valid personal API token (not a project token). Personal tokens are created at https://app.circleci.com/settings/user/tokens. Project tokens do not have the necessary permissions for all tools.
Tools return empty results for pipeline or job queries
Ensure the project you are asking about is followed by your CircleCI account. Use the 'list_followed_projects' tool first to see which projects are accessible, then reference exact project slugs in subsequent queries.
Server fails to start — npx reports package not found
Run 'npx -y @circleci/mcp-server-circleci@latest' once from a terminal to pre-fetch the package from npm. Then restart your MCP client. If behind a corporate proxy, configure npm proxy settings or use the Docker-based installation instead.
Frequently Asked Questions about CircleCI
What is CircleCI?
CircleCI is a Model Context Protocol (MCP) server that specialized server implementation for the model context protocol (mcp) designed to integrate with circleci's development workflow. this project serves as a bridge between circleci's infrastructure and the model context protocol, enabling enhanced a It connects AI assistants to external tools and data sources through a standardized interface.
How do I install CircleCI?
Install via npm with the command: npx -y @circleci/mcp-server-circleci. Then add the server configuration to your AI client's JSON config file (e.g., claude_desktop_config.json or .cursor/mcp.json).
Which AI clients work with CircleCI?
CircleCI works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is CircleCI free to use?
Yes, CircleCI is open source and available under the Apache 2.0 license. You can use it freely in both personal and commercial projects.
CircleCI Alternatives — Similar Developer Tools Servers
Looking for alternatives to CircleCI? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up CircleCI in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use CircleCI?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.