Explore CircleCI projects from your IDE with AI assistance

CircleCI gives you deep visibility into your builds, workflows, and tests, but jumping between browser tabs, copying project URLs, or re-authenticating across tools can slow things down. What if your IDE could just show you the projects you’re working on and let you act on them directly?

This post shows how to use the list_followed_projects tool in the CircleCI MCP server to browse and interact with your CircleCI projects by chatting with an AI assistant inside your IDE. You’ll learn how to list your followed projects, select one to work with, and pass that context to other tools in the server so you can deliver software more effectively, without ever leaving your editor.

Overview

This tutorial walks through:

• Listing all CircleCI projects you’re following
• Selecting one project to use in the current session
• Retrieving build failures from your selected project

To get started, you’ll need:

• A free CircleCI account
• Node.js 18 or later
• An IDE that supports the MCP protocol (such as Cursor or Windsurf)

We’ve included a sample project to test with based on our MCP Cookbook example, but this also works with any CircleCI project you’re following on any supported VCS, including GitHub, GitLab, and Bitbucket.

How it works

When you ask your AI assistant to list your CircleCI projects, it uses the list_followed_projects tool to call the CircleCI API and return all projects you’re currently following. Each one includes a projectSlug, which identifies the project in CircleCI’s system.

After you select a project, the assistant stores that projectSlug in the chat context. From that point on, you can run additional CircleCI tools, like get_latest_pipeline_status or get_build_failure_logs, without needing to specify project details again.

This makes the workflow smoother and lets you move between analysis steps without breaking focus.

Prepare your environment

Before the assistant can access your CircleCI data, you’ll need to authorize it with a personal access token.

1. Go to your CircleCI user settings and create a new personal API token. Copy and store it somewhere safe as you’ll use it to connect your IDE to CircleCI.

2. Configure your IDE to use the MCP Server with the API token you just created. Follow these setup instructions to install and configure the MCP server in your IDE.

This gives the assistant permission to query your CircleCI data and run project-related tools on your behalf.

Step 1: Set up the project

Start by creating a new repository using the contents of this example project. The repo includes a basic structure for testing project interaction tools.

Once the repository is ready, push it to GitHub and connect it to CircleCI by creating a project in your organization named list-followed-projects.

This activates the project in CircleCI and ensures it will appear in your followed projects list. You can double check that a project is followed in the Projects page of your CircleCI dashboard.

Step 2: Open the assistant and list projects

In your IDE, make sure the assistant is running in agent mode. Then open the chat and enter:

list my CircleCI projects

This command uses the list_followed_projects tool to fetch all the CircleCI projects you’re currently following. For each project, you’ll see:

• The project name
• The projectSlug (e.g., gh/your-org/your-repo)

You don’t need to manually copy or reference these slugs. Once a project is selected (we’ll cover that next), the assistant will use it in the background for future operations.

Step 3: Select a project to work with

Once the list appears, choose the project you want to analyze. You can say something like:

select the list-followed-projects repo

or just provide the project number from the list.

The assistant will match the name, extract the corresponding projectSlug, and store it in session context.

Step 4: Interact with your selected project

Once you’ve selected a project, you can start running any supported CircleCI tool without having to provide the projectSlug. The assistant will remember which project you’ve chosen and use it automatically in follow-up requests.

For example, you can ask:

get build failures for the main branch

The assistant will query CircleCI for recent builds on the main branch of your selected project and return a summary of any failures.

Other examples include:

• Getting the status of the latest pipeline run in a project
• Fetching workflow details
• Analyzing flaky tests with get_flaky_tests
• Validating and debugging pipeline configuration

Because the project context is stored, you can continue working across commands without repeating setup or navigating the CircleCI dashboard.

Conclusion

This workflow makes it easy to explore and act on your CircleCI projects without leaving your development environment. By listing your followed projects and selecting one in context, you can use tools like get_build_failure_logs, get_job_test_results, find_flaky_tests, config-helper, and more without copying URLs or switching tabs.

To see what else the CircleCI MCP server can do and how it integrates with AI coding assistants to dramatically accelerate your coding feedback loops, check out the launch blog and the CircleCI MCP Cookbook. Sign up for a free CircleCI account and try it out in your own projects today.