Best for
- Developers using MCP-compatible clients like Cursor, VS Code, Claude Desktop.
- Teams that want to manage CircleCI pipelines seamlessly within their IDE.
- Developers needing quick diagnostics for build failures and test issues.
C
CircleCI MCP Server
Official
Integrate CircleCI development workflows with the Model Context Protocol for AI-powered development.
GitHub source repository ↗
42FMRS · D
A feature-rich MCP server for CircleCI, covering everything from configuration validation to pipeline triggering. However, it is officially deprecated, so migration to CircleCI's hosted MCP or CLI MCP is advised. Easy to install and compatible with major MCP clients.
The CircleCI MCP Server is a specialized server implementation for the Model Context Protocol (MCP) designed to integrate with CircleCI's development workflow. It bridges CircleCI's infrastructure and MCP, enabling enhanced AI-powered development experiences. The server offers tools for configuration validation, test analysis, build logs, artifacts, pipeline triggering, and more. Note: The package is deprecated and no longer receiving feature work; migrate to CircleCI's hosted MCP server or CLI MCP.
Tools
config_helper
Validate and get guidance for your CircleCI configuration.
download_usage_api_data
Download usage data from the CircleCI Usage API.
find_flaky_tests
Identify flaky tests by analyzing test execution history.
find_underused_resource_classes
Find jobs with underused compute resources.
get_build_failure_logs
Retrieve detailed failure logs from CircleCI builds.
get_job_test_results
Retrieve test metadata and results for CircleCI jobs.
get_latest_pipeline_status
Get the status of the latest pipeline for a branch.
list_artifacts
List artifacts produced by a CircleCI job.
list_component_versions
List all versions for a CircleCI component.
list_followed_projects
List all CircleCI projects you're following.
rerun_workflow
Rerun a workflow from start or from the failed job.
run_pipeline
Trigger a pipeline to run.
run_rollback_pipeline
Trigger a rollback for a project.
Setup
- Create a CircleCI Personal API token at https://app.circleci.com/settings/user/tokens. 2. Ensure Node.js >= 18 and pnpm are installed. 3. Add the following JSON to your MCP client config (example for Cursor): {
"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"
}
}
}
}4. Restart your IDE and start using.
claude_desktop_config.json
{
"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"
}
}
}
}
Fit and risk
Not for
- Users needing the latest features and security updates, as the package is deprecated and unmaintained.
- Users seeking a hosted solution; CircleCI's hosted MCP server is recommended.
- Users needing public remote access unless deploying a self-managed remote server with extra security.
Required permissions
- Requires a CircleCI Personal API token (CIRCLECI_TOKEN) with read access to projects.
- In remote mode, requires configuring allowed hosts (MCP_ALLOWED_HOSTS) and authentication.
- File-related tools may read/write files; set MCP_FILE_OUTPUT_ROOTS to restrict root directories.
Risks and side effects
- Token exposure: if the personal or shared token leaks, unauthorized operations may occur.
- Deprecation risk: the server is no longer maintained, potentially with security or compatibility issues.
- Remote mode risk: if authentication is disabled (REQUIRE_REQUEST_TOKEN=false), anyone reaching the port can act on the server.
Troubleshooting
- Clear npx cache: npx clear-npx-cache && npm cache clean --force.
- Ensure using @latest version and fully restart your IDE.
- Check that CIRCLECI_TOKEN is correct and has access to projects.
- For network issues, verify CIRCLECI_BASE_URL is set to https://circleci.com or configure npm proxy.
- For remote mode, ensure MCP_ALLOWED_HOSTS is set to your domain, otherwise you'll get 403.
Use cases
Query pipeline status, build logs, test results, etc., via natural language.
Trigger pipeline runs or rerun workflows directly from your IDE.
Analyze test stability, resource utilization, and optimize CI/CD costs.
Supported clients
CursorFull support
VS CodeFull support
Claude DesktopFull support
Claude CodeFull support
WindsurfFull support
Amazon Q DeveloperFull support