How to Use the CircleCI MCP in Claude Code

Q: Can I use Claude Code to poll a CircleCI job until it finishes?

Yes. You'd write a shell script with a while loop. Inside the loop, call getjobdetails with the job number and check the 'status' field in the JSON response. Break the loop when the status is no longer 'running'.

Q: How do I list all available shared contexts in my organization?

Use the listccicontexts tool. You'll need to provide your organization's ID, slug, or name. The command would be claude mcp exec circleci-mcp listccicontexts orgslug='gh/my-org'.

Pipe your CircleCI status directly into shell scripts. A headless, scriptable interface for your builds, made for Claude Code.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect CircleCI MCP to Claude Code

Create your Vinkius account to connect CircleCI to Claude Code and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup CircleCI with Claude Code

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Build custom deployment scripts

This server exposes CircleCI operations as command-line tools for your agent. You can now `trigger_cci_pipeline` from a simple bash script. This MCP connection lets you treat CircleCI like any other CLI tool, which is perfect for custom automation. For example, write a script that triggers a deployment pipeline, then enters a loop. Inside the loop, it calls `get_workflow_details` every 30 seconds, parsing the JSON output with `jq` to check the status. The script only exits when the build succeeds or fails.

Check build status from the terminal

You're working in a remote SSH session and need to know if the last deployment went through. There's no need to open a browser. Just run a command that tells your agent to `list_cci_pipelines` for your project. Your agent just queries the CircleCI MCP server and pipes the JSON response to your terminal. You get a clean, scriptable list of recent pipelines and their statuses. It's the fastest way to get a pulse check on your project's health from anywhere with a command line.

Generate daily build reports with this MCP Server

Set up a cron job to run a script that calls these tools. Your script can use `list_cci_pipelines` to get all builds from the last 24 hours. For any that failed, it can then use `get_workflow_details` and `list_workflow_jobs` to collect the specific error details. The script can then format this information into a daily summary and send it to a Slack channel or an email address. It's a great way to create an automated, headless monitoring system for your team's CI/CD activity.

Setup guide

Set up CircleCI MCP in Claude Code

Prerequisites

Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
Active Vinkius subscription with a valid endpoint token

1

Run the add command

Open your terminal and run the command shown on the right. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com. Use --scope user to make it available across all projects.
2

Verify the connection

Start a Claude Code session and type /mcp to list connected servers. You should see circleci-mcp with a green status indicator.
3

Start using tools

Ask Claude Code something like "Check my latest CircleCI transactions." It will automatically discover and invoke the available CircleCI tools.

Terminal

claude mcp add --transport http circleci-mcp https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp

Get your connection token →

Prerequisites

Claude Code CLI installed
Active Vinkius subscription with a valid endpoint token

1

Open the config file

Create or edit .mcp.json in your project root for project-level scope, or ~/.claude.json for user-level scope.
2

Add the CircleCI MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Restart Claude Code

Start a new Claude Code session. Type /mcp to confirm the server is connected. The tools will be automatically available in your conversation.

.mcp.json

{
  "mcpServers": {
    "circleci-mcp": {
      "type": "url",
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by CircleCI. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect CircleCI now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about CircleCI MCP in Claude Code

You call the tool through the MCP interface and provide the project slug and branch. The command would look something like `claude mcp exec circleci-mcp trigger_cci_pipeline project_slug='gh/org/repo' branch='main'`. You can pipe the output to `jq`.

Yes. You'd write a shell script with a `while` loop. Inside the loop, call `get_job_details` with the job number and check the 'status' field in the JSON response. Break the loop when the status is no longer 'running'.

It's completely headless and scriptable. This allows you to integrate CircleCI operations into your existing automated workflows, like Git pre-push hooks or your own deployment orchestration scripts, without needing a UI or a browser.

Use the `list_cci_contexts` tool. You'll need to provide your organization's ID, slug, or name. The command would be `claude mcp exec circleci-mcp list_cci_contexts org_slug='gh/my-org'`.

Claude Code only processes what this MCP server returns: metadata about your builds, like pipeline IDs, job statuses, and workflow details. Your CircleCI token is passed through Vinkius's zero-trust proxy for each API call and is never logged or stored.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript