How to add CircleCI MCP Server to Windsurf

Official CircleCI MCP server: inspect and fix failed builds, query pipelines in natural language. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 230★ · stdio · apikey · official

Windsurf config for CircleCI MCP Server

npx -y @circleci/mcp-server-circleci

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "<your-circleci-token>"
      }
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the CircleCI MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5CircleCI MCP Server's tools become available to Cascade.

Before you start

Node.js 18+ (run via npx) or Docker
A CircleCI account with at least one project building on CircleCI
A CircleCI Personal API Token from app.circleci.com/settings/user/tokens (passed via the CIRCLECI_TOKEN env var)
An MCP-compatible client: Cursor, VS Code, Claude Desktop, Claude Code, Windsurf, or Amazon Q Developer

What CircleCI MCP Server can do in Windsurf

get_build_failure_logs

Retrieve detailed logs from a failed build or job to diagnose the cause.

config_helper

Validate a .circleci/config.yml and get guidance on fixing configuration errors.

find_flaky_tests

Identify flaky tests across a project using execution history.

get_job_test_results

Pull test metadata and pass/fail outcomes for a CircleCI job.

get_latest_pipeline_status

Show the current pipeline state for a given branch.

run_pipeline

Trigger a pipeline run for a project/branch.

rerun_workflow

Re-run a workflow from the start or from failed jobs only.

run_rollback_pipeline

Trigger a rollback pipeline for a project.

Security

The CircleCI API token can read project configuration, environment variable names and build logs that may contain secrets; scope it to the minimum projects needed and treat it as sensitive.

CircleCI MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the CircleCI MCP Server config there under the "mcpServers" key and restart the client.

Is CircleCI MCP Server safe to use with Windsurf?

The CircleCI API token can read project configuration, environment variable names and build logs that may contain secrets; scope it to the minimum projects needed and treat it as sensitive.

Is this the official CircleCI MCP server?

Yes. It is maintained by CircleCI under the CircleCI-Public GitHub org and published as @circleci/mcp-server-circleci.

How do I authenticate?

Create a Personal API Token in your CircleCI user settings and provide it via the CIRCLECI_TOKEN environment variable in your MCP client config.

Which clients are supported?

Cursor, VS Code, Claude Desktop, Claude Code, Windsurf, Amazon Q Developer, and other MCP-compatible clients. It also installs via Smithery.

View repo Full CircleCI MCP Server page