Getting started with Cursor and CircleCI: Adding AI to CI/CD workflows

AI coding assistants have transformed how developers write and debug code. But there’s a gap: these assistants often can’t see what’s happening in your CI/CD pipelines. When a build fails, you’re still stuck switching tabs, hunting through logs, and copying error messages back into your editor.

What if your AI assistant could talk directly to CircleCI?

In this tutorial, you’ll learn how to connect Cursor, an AI-powered code editor, to CircleCI using the CircleCI MCP server. Once connected, you can validate configs, trigger pipelines, diagnose failures, and analyze test results using natural language, all without leaving your IDE.

While we’re focusing on Cursor here, the CircleCI MCP server also works with other MCP-compatible tools like Claude Desktop, VS Code, and Windsurf. The setup process is similar across all of them.

Prerequisites

Before you start, make sure you have:

• A CircleCI account
• A GitHub account
• Node.js 18 or newer installed locally
• Cursor installed

What is Cursor?

If you’re new to Cursor, here’s a quick overview. Cursor is an AI-powered code editor built on VS Code. It looks and feels familiar, but adds powerful AI capabilities that can help you write, refactor, and debug code faster.

The key feature we’ll use is Agent mode. Unlike simple chat assistants that just answer questions, Agent mode can:

• Make changes across multiple files
• Run terminal commands on your behalf
• Understand context from your entire codebase
• Iterate on solutions until they work

To open the AI pane, press Cmd+L (Mac) or Ctrl+L (Windows/Linux). You’ll see a mode picker at the bottom. Select Agent to unlock the full capabilities we’ll use in this tutorial.

For a deeper dive into Cursor’s features, check out the official Cursor documentation.

Setting up your CircleCI project

Before the MCP server can interact with your pipelines, you need a project connected to CircleCI with at least one pipeline run. If you already have this set up, you can skip to the next section.

Using the demo repository

The easiest way to follow this tutorial is to use our demo repository. It includes a Node.js project with tests and a pre-configured .circleci/config.yml file.

1. Fork the repository to your GitHub account
2. Create a new project in CircleCI and connect it to your forked repository
3. Trigger a build by pushing a commit (or let CircleCI run the initial build automatically)

Once your project shows up in the CircleCI dashboard with at least one pipeline run, you’re ready to continue.

Using your own project

If you’d prefer to use an existing project:

1. Make sure your repository has a .circleci/config.yml file defining your pipeline
2. Ensure the project is connected to CircleCI
3. Verify you can see pipeline runs in the CircleCI dashboard

For help creating your first configuration, see the CircleCI configuration introduction.

Setting up the CircleCI MCP server

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. The CircleCI MCP server uses this protocol to give your AI assistant direct access to your pipeline data: build logs, test results, configuration validation, and more.

Here’s how to set it up in Cursor.

Step 1: Generate a CircleCI Personal API Token

Your AI assistant needs permission to access your CircleCI data. You’ll grant this through a personal API token.

1. Log in to CircleCI
2. Go to User Settings → Personal API Tokens
3. Click Create New Token
4. Give it a name (e.g., “Cursor MCP”) and copy the token

Store this token somewhere safe. You’ll need it in the next step. For more details, see the CircleCI token documentation.

Step 2: Add the MCP configuration to Cursor

Cursor stores MCP server configurations in a JSON file. You can set this up globally (for all projects) or per-project.

For a global configuration, create or edit the file at ~/.cursor/mcp.json and add:

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

Replace your-circleci-token with the token you generated in Step 1.

Step 3: Verify the connection

After saving your configuration:

1. Restart Cursor (or reload the window)
2. Go to Cursor Settings → MCP
3. You should see circleci-mcp-server listed with its available tools

If the tools don’t appear, try clicking the refresh icon in the MCP settings panel. If you’re still having trouble, double-check that your API token is valid and that Node.js 18+ is installed.

Pointing Cursor at your CircleCI project

Before you can run commands like “validate my config” or “why did my build fail,” the MCP server needs to know which CircleCI project you’re working with. This step is essential. Without it, the server won’t know where to look for your pipelines.

The good news: if you open your project folder in Cursor, the MCP server can usually identify your project automatically by reading your Git remote configuration.

Step 1: Open your project in Cursor

Launch Cursor and open the folder containing your CircleCI project. This should be a Git repository with:

• A remote pointing to GitHub, GitLab, or Bitbucket
• A .circleci/config.yml file
• A corresponding project in your CircleCI account

If you’re using the demo repository, open your forked copy.

Step 2: Verify the connection

Open the AI pane (Cmd+L or Ctrl+L) and switch to Agent mode. Then ask:

List my followed projects on CircleCI

The assistant will use the list_followed_projects tool to show all CircleCI projects associated with your account. Look for your project in the list. You’ll see its project slug (e.g., gh/your-username/your-repo).

If your project appears in the list, you’re all set. The MCP server will automatically target the correct project based on your current Git remote and branch.

Troubleshooting

If your project doesn’t appear:

• Make sure you’ve followed the project in CircleCI (it should show in your CircleCI dashboard)
• Verify your Git remote is correctly configured (git remote -v)
• Check that your CircleCI API token has the necessary permissions

Tip: If you need to work with a different project than the one in your current directory, you can specify a project URL or slug directly in your prompts. For example: “Get the latest pipeline status for gh/my-org/other-repo”

Now that Cursor knows which project to target, let’s put the integration to work.

Use case 1: Validate your CircleCI config

Let’s start with something simple but valuable: validating your CircleCI configuration before you push.

Catching syntax errors or misconfigurations early saves you from failed builds and wasted pipeline minutes. Instead of running a CLI command or pushing to see what happens, you can ask your AI assistant to validate the config right from your editor.

In the AI pane, try:

Validate my CircleCI config

The assistant will use the config_helper tool to check your .circleci/config.yml file. You’ll get back:

• Validation results (pass/fail)
• Specific errors or warnings, if any
• Recommendations for improving your configuration

This is especially useful when you’re editing complex configs with multiple workflows, orbs, or conditional logic. You get instant feedback without leaving your editor.

Use case 2: Trigger a pipeline from your IDE

Sometimes you want to kick off a build without pushing a commit. Maybe you’re testing infrastructure changes or re-running after a flaky failure. With the CircleCI MCP server, you can trigger pipelines using natural language.

In the AI pane, try:

Run the pipeline for my current branch

The assistant will use the run_pipeline tool to trigger a build. It reads your Git remote and branch automatically, so you don’t need to specify project details. You’ll get back a confirmation and a link to monitor the pipeline in CircleCI.

If you follow the link, you can see the pipeline’s status and interact with it via the CircleCI UI. But in most cases, you can get the information you need directly in Cursor without breaking your development flow.

You can also be more specific when asking the MCP server to trigger the pipeline. You can specify which branch to run:

Run the pipeline for the develop branch

Or provide a direct project URL if you’re working across multiple repositories.

Use case 3: Diagnose a failed build

This is where the integration really shines. When a build fails, the traditional workflow looks like this: open CircleCI, find the failed pipeline, click through to the job, scroll through logs, copy the error, paste it back into your editor, and try to figure out what went wrong.

With the MCP server, you can get this information directly from Cursor.

When your build fails, just ask:

Why did my last build fail?

The assistant calls the get_build_failure_logs tool, which retrieves structured data from your most recent failed pipeline. You’ll see:

• Which job and step failed
• The full command output
• Exit codes and error messages
• Contextual information to help diagnose the issue

Once Cursor retrieves the error details, it immediately analyzes the failure and suggests specific changes to fix the issue. You’ll see the assistant explain what went wrong and propose edits to your code or configuration files.

If you approve the suggestion, Agent mode applies the changes directly. No copy-pasting required. For example, if your build failed due to a missing dependency, the assistant might update your package.json and run npm install for you. If it’s a configuration issue in .circleci/config.yml, it will edit the file and explain what it changed.

Iterating until the build passes

After applying a fix, you can ask the assistant to trigger a new build and monitor the results:

Run the pipeline and let me know if it passes

If the build fails again, the assistant fetches the new error logs, diagnoses the next issue, and suggests another fix. This creates a tight feedback loop: fix, build, check, repeat. All without leaving your editor.

For complex issues that require multiple iterations, this workflow dramatically reduces the time between “build failed” and “build passing.”

You can also provide a specific pipeline URL if you want to investigate a particular build:

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

Use case 4: Analyze test results

Failed tests are one of the most common reasons builds break. The CircleCI MCP server can pull test metadata directly into your editor, making it easy to understand what’s failing and why.

Try asking:

Show me the test results from the last pipeline

The assistant uses the get_job_test_results tool to retrieve test metadata, including:

• Test names and file locations
• Pass/fail status
• Failure messages and stack traces
• Performance metrics

If you only care about failures, you can filter:

Show me only the failed tests from the last build

This is particularly helpful when you have a large test suite and don’t want to scroll through hundreds of passing tests to find the few that broke.

Bonus: Find flaky tests

If your team struggles with tests that pass sometimes and fail other times, the find_flaky_tests tool can help. It analyzes your test history to identify patterns of instability:

Find flaky tests in my project

You’ll get a list of unreliable tests along with context about their failure patterns, helping you prioritize which tests to fix or quarantine.

Run CircleCI CLI commands from Cursor

The MCP server connects Cursor to CircleCI’s cloud infrastructure, fetching data from your actual pipeline runs. But sometimes you want to work locally: validating config changes before pushing, or running jobs on your own machine to debug issues faster.

That’s where the CircleCI CLI comes in. And since Cursor’s Agent mode can execute terminal commands, you can use the CLI through natural language too.

Local config validation

The MCP server’s config_helper tool validates your config against CircleCI’s servers. The CLI offers a local alternative that works offline:

Run circleci config validate in the terminal

This checks your .circleci/config.yml for syntax and structural errors without making any API calls. It’s faster for quick iterations when you’re editing your config.

Running jobs locally

Want to test a job without pushing to GitHub and waiting for CircleCI’s cloud? The CLI can run jobs in a local Docker container:

Use the CircleCI CLI to run the build job locally

This executes circleci local execute --job build, spinning up a container on your machine that mimics the CircleCI environment. It’s useful for debugging environment-specific issues or testing changes before committing.

When to use which

Approach	Best for
MCP server	Checking real pipeline status, fetching actual build logs, analyzing test results from CI runs
CircleCI CLI	Offline config validation, local job execution, faster iteration during config development

Both approaches work seamlessly through Cursor’s Agent mode. If you don’t have the CLI installed yet, check out the installation guide.

Summary

You’ve now connected Cursor to CircleCI and learned how to:

• Validate configurations before pushing, catching errors early
• Trigger pipelines without leaving your editor
• Diagnose failed builds using natural language instead of log hunting
• Analyze test results to quickly identify and fix failures

This is just the beginning. The CircleCI MCP server includes additional tools for rollbacks, project discovery, and more. As you integrate this into your daily workflow, you’ll find yourself spending less time context-switching and more time shipping code.

Conclusion

The combination of Cursor and the CircleCI MCP server opens up a new way of working with CI/CD. Instead of treating your pipelines as something separate from your coding workflow, you can interact with them naturally: asking questions, triggering builds, and fixing failures without ever leaving your editor.

Once you’ve got the integration set up, explore the MCP Cookbook for more examples and patterns. You’ll find real-world scenarios for debugging flaky tests, optimizing pipeline performance, and more. The CircleCI MCP Server documentation and GitHub repository are also great resources as you dig deeper.

Ready to give it a try? Sign up for a free CircleCI account and start building.