Trigger CircleCI pipelines from your IDE with natural language

Most CircleCI pipelines are configured to trigger automatically on code commits, but not every development scenario fits that model. Sometimes you need to trigger a build manually—to test pipeline changes, retry a flaky test, or run CI on a colleague’s branch—without the friction of pushing empty commits or navigating to the UI to manually trigger a build.

In this tutorial, you’ll learn how to trigger and monitor CircleCI pipelines directly from your IDE using natural language prompts. With the CircleCI MCP server, you can simply ask your AI assistant to

run a pipeline on the main branch 

and immediately kick off a pipeline, get status updates, and generate bug fixes, all without leaving your editor.

This example is based on a real-world workflow from our CircleCI MCP Server Cookbook, where you can find more patterns for integrating CI control into your development process.

Setting up the example project

Before you start, make sure you have:

• A CircleCI account
• A GitHub account
• Node.js 18 or newer installed locally
• An IDE that supports MCP server integration (Cursor, Windsurf, Claude Code, etc.)

For this tutorial, we’ve provided a sample repository with a working CircleCI pipeline that’s ready to trigger. You can fork this project to follow along with the examples.

However, this workflow works with any CircleCI project you have write access to. If you’d prefer to use an existing project, simply ensure it’s connected to CircleCI and you have the necessary permissions to trigger builds.

If using the sample project, fork the repository and head to CircleCI to create a new project titled run-pipeline. Connect it to your forked repository so that builds can be triggered both automatically and manually. After the project is connected, you’re ready to move forward.

Preparing your environment

For your assistant to control CircleCI pipelines, you’ll need to authorize it with your account.

Log in to CircleCI and generate a personal access token under User Settings > Personal API Tokens. This token allows the MCP server to trigger builds and query pipeline status securely. Save it somewhere safe as you’ll need it for the next step.

Next, configure your IDE to use the MCP Server. During setup, you’ll provide your CircleCI personal API token as part of the MCP server configuration. This authorizes the server to access and control pipelines for your projects.

Once connected, your assistant can trigger builds, check pipeline status, analyze failures, and suggest fixes, all without switching tools or opening the CircleCI dashboard.

Discovering your projects

Open the chat window in your IDE and start by listing your available CircleCI projects:

list my CircleCI projects

The assistant will call the CircleCI MCP server and return a structured list of projects you’re following.

Each project includes essential details like the project name and projectSlug (formatted as vcs/organization/repository-name).

Next, select the project you want to work with:

select the run-pipeline project

This establishes project context so you won’t need to specify the project details in subsequent commands. The assistant stores the projectSlug and uses it for all future pipeline operations.

Triggering a pipeline

With your project selected, trigger a pipeline by specifying the target branch:

run a pipeline on the main branch

The assistant will use the run_pipeline tool to make the API call to CircleCI’s pipeline trigger endpoint. You’ll get back a direct link to the newly created pipeline where you can monitor its progress.

This is much faster than navigating to the CircleCI dashboard, finding your project, and manually triggering a build through the UI.

Monitoring pipeline status

If you follow the link supplied by the run_pipeline tool, you will see your pipeline running in CircleCI.

Instead of leaving your IDE to check pipeline status, you can also ask your assistant:

what's the status of the latest pipeline?

The assistant will use the get_latest_pipeline_status tool to retrieve real-time information about your most recent pipeline execution. You’ll get a structured response with pipeline state, execution time, and job-level status directly in your IDE.

When this workflow shines

Manual pipeline triggering is particularly valuable in several scenarios:

-Testing CI configuration changes: You can test the execution of pipeline config changes without committing potentially broken configurations to your main branch.

• Retrying flaky or transient failures: Network timeouts, rate limits, or temporary service unavailability can be cleanly retried without investigating whether the failure was environmental or code-related. (You can also use the find_flaky_tests tool to quickly identify and fix flaky tests in your project.)

• Running expensive or scheduled workflows: You can trigger resource-intensive pipelines (like full integration tests or performance benchmarks) on-demand rather than waiting for scheduled runs or running them on every commit.

• Coordinating releases: When preparing releases that span multiple repositories, you can trigger builds across different projects in sequence without the complexity of synchronized commits or setting up pipelines to trigger other pipelines.

In each of these cases, being able to trigger pipelines conversationally eliminates the friction of context switching and keeps you focused on the development task at hand.

Summary

Triggering pipelines without making code changes often means breaking your development flow: either pushing empty commits or switching to the CircleCI dashboard to manually start builds.

By connecting your assistant to CircleCI through the MCP Server, you eliminate that overhead. Your assistant handles the API interactions, project selection, and status monitoring, keeping you focused on development rather than CI management.

Automatic pipeline triggers work well for standard development workflows, but the CircleCI MCP server offers increased control when you need it, delivered through the same natural language interface you’re already using for coding assistance.

We’re actively building out the CircleCI MCP Server Cookbook with more examples you can use to integrate CI feedback seamlessly into your development process.

Sign up for a free CircleCI account today and install the CircleCI MCP server to start bringing pipeline control directly into your development workflow.