Getting started with Claude Code and CircleCI

AI-powered coding tools are changing how developers work. Tools like Claude Code can write functions, refactor code, and build features through natural conversation, often faster than you could type them yourself. But speed creates its own risks. AI-generated code can contain subtle bugs, reference packages that don’t exist, or misuse APIs in ways that only surface at runtime.

That’s where continuous integration comes in. CI is a safety net that lets you move fast confidently. When you pair an AI coding assistant with automated testing and validation, you get the best of both worlds: rapid development with reliable verification.

This tutorial guides you through setting up Claude Code, connecting it to CircleCI, and creating a workflow where AI-generated code gets validated automatically. The whole setup takes just a few minutes. Once it’s in place, you can iterate quickly knowing that your CI pipeline will catch problems before they reach production.

What you’ll need

Before you get started, make sure you have these pieces in place:

• A CircleCI account (the free tier is perfect for this)
• A GitHub account
• Node.js 18 or later on your machine
• Claude Code installed and working

A quick introduction to Claude Code

Claude Code is Anthropic’s command-line tool that puts Claude directly in your terminal. Rather than switching between your editor, a chat window, and various dashboards, you can have a conversation with Claude right where you’re already working.

What makes Claude Code particularly powerful for CI/CD workflows is its support for MCP: the Model Context Protocol. MCP lets you extend Claude’s capabilities by connecting it to external services. Once connected, Claude can use these services as naturally as it reads files or runs commands. For this tutorial, you’’ll connect it to CircleCI so Claude can fetch build logs, trigger pipelines, and analyze test failures for you.

To install Claude Code, you can use npm:

npm install -g @anthropic-ai/claude-code

After installation, run claude to start it up. You’ll authenticate with your Anthropic account, and then you’re ready to go.

Why you need CI with AI-assisted development

AI coding assistants are powerful, but they’re not infallible. Here’s what can go wrong:

Hallucinated dependencies: AI models sometimes reference packages that don’t exist or use outdated package names. Your code looks fine until npm install fails in CI.

Incorrect API usage: The model might use an API method with the wrong signature, pass arguments in the wrong order, or call deprecated functions. These errors often compile but fail at runtime.

Missing edge cases: AI-generated code tends to handle the happy path well but can miss null checks, error handling, or boundary conditions that your tests will catch.

Security vulnerabilities: Without careful prompting, AI might generate code with SQL injection risks, improper input validation, or other security issues that automated scanning can flag.

Integration mismatches: Code that works in isolation might break when it interacts with the rest of your system. Only integration tests running in CI will surface these problems.

The solution isn’t to avoid AI tools—it’s to verify their output automatically. A CI pipeline running your tests, linters, and security scans after every change means you can accept AI suggestions confidently. If something’s wrong, you’ll know within minutes.

Getting started with CircleCI

If you don’t already have CI set up, CircleCI makes it straightforward. Here’s the quick version:

1. Sign up at circleci.com using your GitHub, Bitbucket, or GitLab account
2. Create a project by selecting your repository from the CircleCI dashboard
3. Add a config file at .circleci/config.yml in your repository

A minimal configuration looks like this:

version: 2.1

jobs:

  build-and-test:

    docker:

      - image: cimg/node:20.0

    steps:

      - checkout

      - run: npm install

      - run: npm test

workflows:

  main:

    jobs:

      - build-and-test

Once you push this file, CircleCI will automatically run your pipeline on every commit.

For detailed setup instructions, language-specific examples, and advanced configuration options, see the CircleCI Quickstart Guide.

Getting a CircleCI project ready

For this tutorial to be useful, we need a project with some CI/CD history: builds that have run, maybe some that have failed, tests that have executed. You can either fork a demo repository or use something you’re already working on.

Fork the demo repository

If you want a quick way to follow along, fork this ecommerce demo project that already has CircleCI configured:

1. Visit github.com/rogerwintercircleci/smarter-testing-ecommerce and fork it to your account
2. Go to CircleCI and click Projects
3. Locate your forked repo and click Set Up Project
4. Let CircleCI run the initial pipeline

Use your existing project

Already have a project running on CircleCI? That works perfectly. Just confirm that:

• There’s a .circleci/config.yml in the repository
• The project is connected and visible in your CircleCI dashboard
• You have at least a few pipeline runs to query

Connecting Claude Code to CircleCI

The magic happens through CircleCI’s MCP server, which exposes CircleCI’s functionality in a way Claude Code can understand and use. Setup is straightforward and takes just a couple of minutes.

Create your CircleCI API token

First, we need an API token so Claude Code can authenticate with CircleCI:

1. Log into CircleCI
2. Click your avatar in the bottom-left corner
3. Go to User Settings
4. Select Personal API Tokens from the sidebar
5. Click Create New Token
6. Name it something memorable like “Claude Code Integration”
7. Copy the token immediately (CircleCI won’t show it again)

Keep this token handy; you’ll need it in the next step.

Configure the MCP server

Claude Code can read MCP configurations from a couple of places. For a setup that works across all your projects, we’ll use ~/.claude.json. If you want project-specific configuration, you can alternatively use .mcp.json in your project root.

Create or edit ~/.claude.json:

On macOS or Linux:

shell
nano ~/.claude.json

On Windows (PowerShell):

notepad $env:USERPROFILE\.claude.json

Add this configuration, substituting your own token:

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

If you prefer not to hardcode the token, Claude Code supports environment variable expansion:

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

Then export the variable in your shell profile:

export CIRCLECI_TOKEN="your-circleci-token-here"

Verify the connection

Restart Claude Code to pick up the new configuration, then check that everything is working:

/mcp

circleci is listed with a “connected” status. If it shows “failed”, double-check your token and make sure Node.js is installed.

For a real test, ask Claude to pull your projects:

What CircleCI projects am I following?

If Claude returns a list of your projects, you’re all set.

Validating your pipeline configuration

Now put this integration to work. One of the most immediately useful things you can do is validate your CircleCI config before pushing changes. No more discovering syntax errors after you’ve already committed.

Try asking:

Check if my CircleCI configuration is valid

Claude will use the MCP server to validate your .circleci/config.yml and report back with any issues it finds. You’ll get specific error messages with line numbers, warnings about potential problems, and suggestions for improvements.

This is especially valuable when you’re modifying a complex pipeline or trying out new orbs. Catch the mistakes before they cost you a failed build.

Triggering builds from your terminal

Here’s something that saves more time than you might expect: kicking off pipeline runs without leaving your terminal. Instead of navigating to CircleCI, finding your project, and clicking through the UI, just ask:

Start a pipeline for my current branch

Claude detects your Git remote and branch, triggers the build, and gives you a link to monitor it if you want. You can also be more specific:

Or target a completely different project:

Run the pipeline for the staging branch

When you’re iterating on a fix and need to run the pipeline multiple times, staying in your terminal keeps you focused.

Investigating build failures

This is where the integration really proves its worth. When something breaks, you don’t want to go hunting through logs—you want answers.

Ask Claude:

What happened in my last failed build?

Claude fetches the failure logs and breaks down what went wrong. You’ll see which job failed, which step caused the problem, the actual error output, and relevant context from the surrounding steps.

But Claude doesn’t stop at showing you the error. It analyzes the failure and suggests how to fix it. Since you’re already in your terminal with the code right there, you can make the fix immediately.

Create a feedback loop

You can take this a step further by asking Claude to handle the entire cycle:

Fix that issue and run the pipeline again. Let me know when it passes.

Claude will make the code changes, commit them, trigger a new build, and report back with the results. If something else breaks, you can keep iterating until everything passes—all without switching contexts.

Look at a specific build

Sometimes you need to investigate a particular pipeline run, maybe one from yesterday or one a teammate mentioned:

Show me what happened in this build: https://app.circleci.com/pipelines/github/my-org/my-repo/456

Analyzing test results

When tests fail, you need to know exactly which tests, what the assertions were, and where in the code the failures occurred.

Ask Claude:

What were the test results from my last pipeline?

You’ll get a breakdown including test names and their file locations, pass/fail status, failure messages with stack traces, and timing data that might reveal slow tests.

To zero in on problems:

Just show me the failing tests from that build

Tracking down flaky tests

Few things are more frustrating than tests that pass sometimes and fail other times. They undermine confidence in your test suite and waste time on unnecessary reruns.

Are there any flaky tests in this project?

Claude can analyze test history to identify tests with inconsistent results, giving you a prioritized list of tests that need attention.

Running local validations

The MCP server connects Claude to CircleCI’s cloud APIs, but sometimes you want faster, local feedback. If you have the CircleCI CLI installed, Claude can use that too.

Validate my config locally with the CircleCI CLI

This runs the validation without any API calls—faster and works offline.

Execute the build job locally using the CircleCI CLI

This spins up Docker containers that simulate the CircleCI environment, letting you debug job failures without pushing commits.

Which approach to use

Approach	When to use it
MCP server	Fetching real build logs, checking pipeline status, triggering remote builds, analyzing test results
CircleCI CLI	Quick local config validation, running jobs locally, rapid iteration without remote round-trips

You don’t have to pick just one—use whichever fits the task at hand.

When things don’t work

MCP server not connecting

If /mcp shows the CircleCI server as “failed”:

1. Validate that your ~/.claude.json is proper JSON (a linting tool helps here)
2. Confirm Node.js 18+ is installed: node --version
3. Test the MCP server directly:

shell
CIRCLECI_TOKEN=your-token npx @circleci/mcp-server-circleci@latest

1. Restart Claude Code after any configuration changes

Project not recognized

If Claude can’t find your project:

1. Verify the project shows up in your CircleCI dashboard
2. Check your Git remote: git remote -v
3. Make sure your API token has appropriate permissions
4. Specify the project explicitly: Get build status for gh/my-username/my-repo

Authentication failures

If you’re getting token errors:

1. Confirm the token is still valid in CircleCI’s User Settings
2. Generate a fresh token and update your configuration
3. Watch out for trailing whitespace or newlines in the token value

Bringing it together

AI coding tools let you build faster than ever, but speed without verification is just a faster way to ship bugs. By pairing Claude Code with CircleCI, you get the productivity benefits of AI-assisted development with the confidence that comes from automated testing.

With the setup in this guide, you can write code through natural conversation with Claude, validate changes automatically before they cause problems, diagnose and fix failures without leaving your terminal, and iterate rapidly with a tight feedback loop between coding and testing.

Getting started takes just a few minutes: install Claude Code, connect it to CircleCI via MCP, and you’re ready to go. The investment pays off immediately: every time you catch an AI-generated bug before it reaches production, every time you fix a failing build without opening a browser.

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