CircleCI MCP server: Natural language CI for AI-driven workflows

The pace of software development has changed. With AI coding assistants now embedded into engineering workflows, developers are building faster, shipping sooner, and writing more code than ever before. But as velocity increases, so does the complexity of keeping that code running.

When builds fail, developers need answers fast. They need clarity, context, and actionable feedback right where they’re working.

The CircleCI MCP Server is a new way to connect your assistant to your CI pipelines. It’s a CI-focused server built on the Model Context Protocol (MCP) and gives AI tools direct access to logs, job metadata, and failure context. Assistants can identify issues in real time, suggest fixes, and even apply them, all through natural language prompts.

This is CI that understands your code, your context, and your intent. It bridges the gap between code generation and system understanding, making CI a more integrated part of the development feedback loop.

What is MCP?

Model Context Protocol (MCP) is an open standard that lets large language models (LLMs) securely and intelligently interact with developer tools.

It provides a structured way for coding assistants to access live context from systems like Git, CI/CD providers, or test runners. Instead of relying on vague prompts, assistants can:

• Call specific tools exposed by the system
• Use project-aware context from your local environment
• Receive structured data as output (e.g., parsed logs, job metadata, failure reasons)
• Use that data to offer actionable suggestions or make changes

The CircleCI MCP Server is an implementation of MCP designed for CI workflows. It bridges your assistant and your CI system, so you can ask questions like:

• “What failed on my last deploy?”
• “Help me fix this broken pipeline.”
• “Which tests are flaky in this project?”

And get structured answers your assistant can work with, instead of needing to dig through the CircleCI UI manually.

What the CircleCI MCP server can do

The CircleCI MCP server is in active development and currently supports two key tools: get_build_failure_logs and find_flaky_tests.

✅ get_build_failure_logs

This tool retrieves logs from failed CircleCI jobs or pipelines and returns structured, readable output your assistant can use. There are two ways to identify which job to fetch:

• Pass a job or pipeline URL directly:

    Get logs from https://app.circleci.com/pipelines/github/my-org/my-repo/456
  

• Use your local Git project context:

  The server reads your Git remote and active branch to identify the relevant CircleCI project and pipeline. You can also specify any branch explicitly:

    Find the latest failed job on the main branch
  

In both cases, the response includes:

• Job and step details
• Full command logs
• Exit codes and failure messages

With this information, the assistant can diagnose the issue, summarize the failure in plain language, and suggest changes that resolve the problem, all without the developer needing to switch tools or search manually.

🔍 find_flaky_tests

This tool helps identify flaky tests in your CircleCI project by analyzing your test execution history. It uses CircleCI’s flaky test detection to surface patterns and provide rich context on unreliable tests.

There are two ways to use it:

• Using a CircleCI project URL:

    Find flaky tests in https://app.circleci.com/pipelines/github/org/repo
  

• Using your local project context:

    Find flaky tests in my current project
  

The tool returns structured information including:

• Test names and file locations
• Failure messages and failure context

This helps your assistant detect instability in your test suite and provide data-driven suggestions for improving test reliability.

Real-world workflows

The CircleCI MCP Server is designed to support real moments in the development lifecycle. Whether you’re reviewing a broken build, debugging a failed deploy, or keeping tabs on a critical branch, it helps your assistant understand failures and suggest fixes in seconds — no context-switching required.

1. A PR check fails, and you need to unblock it

You push a change, the build fails, and you’re not sure why. Instead of jumping into the UI, you ask:

Why did this PR’s build fail?

The assistant identifies a missing environment variable in the db:setup step and offers to update your config file. You approve the fix, re-run the job, and continue your review without leaving your IDE.

2. A staging deploy breaks, and you’re trying to ship

Right before a release, the deploy to staging fails. You drop in the pipeline link:

Get logs from https://app.circleci.com/pipelines/github/my-org/my-repo/789 and help me fix it

The server returns structured logs from the failed job. Your assistant identifies a missing secret, confirms the absence in your .env file, and suggests a secure patch. You apply the change and ship a fix immediately.

3. Flaky tests are killing your momentum

You’re spending time chasing test failures that aren’t real: re-running jobs, second-guessing changes, and losing trust in your pipeline. It’s slowing you down and disrupting the fast, confident feedback loop your team depends on.

You prompt:

Find and fix flaky tests in my project

The server analyzes historical test results to surface the most unreliable tests, with names, locations, failure rates, and full context. Your assistant helps you understand what’s flaky, why it matters, and how to fix it so you can get back to building with confidence.

These workflows highlight how the CircleCI MCP Server helps transform broken or unreliable builds into moments of clarity. With structured data and AI assistance working together, teams resolve issues faster and move forward with confidence.

Use it with Cursor, Cline, Windsurf, and more

The CircleCI MCP Server works with any IDE or assistant that supports the Model Context Protocol. Getting started is simple. All you need is:

• A CircleCI API token with read access
• An assistant that supports MCP
• A minimal config to connect the server

For example, in Cursor, you can connect the server by adding this to your MCP config:

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

Once connected, you can prompt:

Find the latest failed build on my branch and help me fix it

That’s it. The server takes care of talking to CircleCI and structuring the data; your assistant figures out what went wrong and how to fix it.

Explore the project

The CircleCI MCP Server is open source and ready to use. Check out the repo → https://github.com/CircleCI-Public/mcp-server-circleci

Have ideas, run into issues, or want to help shape its future? Contributions are welcome. Open a pull request or start a discussion in the repo.

By connecting assistants directly to your CI pipeline, the CircleCI MCP Server helps developers and AI work together to understand, fix, and learn from build failures faster than ever. Whether you’re setting up continuous integration for the first time or finally ready to upgrade to world-class CI/CD, you can start building in minutes with a free CircleCI account.

Builds fail. Now your assistant can help fix them.