# CircleCI MCP for AI Agents MCP

> CircleCI connects your automated build and deployment pipelines to any AI agent, letting you manage complex CI/CD workflows using plain conversation. You can list recent builds, check job statuses, trigger manual deployments, and view environment contexts without ever opening the CircleCI dashboard.

## Overview
- **Category:** ship-it
- **Price:** Free
- **Tags:** continuous-integration, continuous-deployment, pipeline-automation, build-automation, workflow-orchestration, software-delivery

## Description

Managing software releases used to mean clicking through endless dashboards—a tedious process of checking status codes, cross-referencing branch names, and manually hitting 'run'. This MCP changes that. It gives your AI client direct control over your entire CI/CD lifecycle. You can ask your agent to list all recent pipelines across multiple projects or check the deployment status of a specific job simply by talking to it.

With this integration, you're not just getting read-only access; you can initiate actions, like triggering an immediate run for a critical branch. If you already use other tools in your stack, connecting via Vinkius makes sure that all your operational intelligence is available from one place, letting you focus on writing code and shipping features, not managing dashboards.

## Tools

### get_my_cci_profile
Retrieves basic information about the authenticated user within your CircleCI account.

### get_workflow_details
Fetches detailed information for a specific, named workflow template.

### list_cci_contexts
Lists all shared environment contexts available across your entire organization.

### list_workflow_jobs
Retrieves a list of every individual job that belongs to a specific workflow template.

### list_cci_pipelines
Lists the status and details for your most recent CI/CD pipelines across all projects.

### trigger_cci_pipeline
Manually starts a new pipeline run for a designated project or repository branch.

### get_job_details
Retrieves detailed execution metadata and status for a specific, running job instance.

### list_pipeline_workflows
Shows all available workflows associated with a single, completed pipeline run.

## Prompt Examples

**Prompt:** 
```
What were the results for my web app deployment yesterday?
```

**Response:** 
```
**Build Status Summary**

*   Project: `web-app` (Repo ID 456)
*   Last Run: Yesterday, 3:15 PM UTC
*   Status: **FAILED**

**Details:** The workflow ran successfully up to the testing stage. However, the final deployment job failed with error code 500. You need to check `web-app`'s logs for more info.
```

**Prompt:** 
```
Can you start a new build right now for the main branch?
```

**Response:** 
```
**🚀 Pipeline Initiated!**

I've triggered a fresh pipeline run for `main` on project `api-gateway`. The process is starting immediately. You can track its progress using this ID: `550e8400-...`.

Please monitor the job list below for status updates.
```

**Prompt:** 
```
Show me all available workflows for the API service:
```

**Response:** 
```
**API Service Workflows Found:**

*   `build-core`: Builds and packages core libraries.
*   `test-integration`: Runs end-to-end integration tests.
*   `deploy-staging`: Manually deploys to the staging environment (Requires approval).

Which one do you want details on?
```

## Capabilities

### View Build History
List and retrieve full details for recent CI/CD pipelines across every configured organization.

### Start New Pipelines
Manually trigger a new pipeline run on specific projects or branches when needed.

### Check Workflow Statuses
Access comprehensive information about workflows and the individual jobs that make them up.

### Audit Job Failures
Get detailed metadata, including the exact execution status, for any specific job run.

### Manage Environments
List shared environment contexts used to secure sensitive project data across your organization's projects.

## Use Cases

### The 'Staging Environment' Check
A release manager needs to confirm if the staging environment is ready for a new feature branch. They ask their agent, and it uses `list_cci_pipelines` to show the last three successful builds on that specific branch, confirming readiness.

### Debugging an Intermittent Build Failure
A developer notices a flaky build in production. Instead of guessing, they ask their agent to use `get_job_details` for the failed job ID. The agent returns the specific error logs and execution status instantly.

### Forcing an Urgent Hotfix Build
A critical bug is found in production. A team member asks their agent to trigger a new pipeline for the hotfix branch. The agent uses `trigger_cci_pipeline` and confirms the new run ID, starting the fix immediately.

### Understanding Project Dependencies
An infrastructure engineer needs to know which shared variables are used across multiple microservices. They ask the agent to list all contexts using `list_cci_contexts`, giving a clear map of dependencies.

## Benefits

- Immediate visibility into build failures. Use `get_job_details` to pull up specific job metadata, telling you exactly *why* a deployment failed without deep diving into logs.
- Control the release cycle directly via chat. You can manually start deployments for critical branches using `trigger_cci_pipeline`, perfect when an automated gate needs human approval.
- Understand your entire infrastructure scope. Running `list_cci_contexts` shows you every shared environment variable used by projects, helping manage sensitive data access.
- Consolidated status checks. Instead of checking five different dashboards, running `list_cci_pipelines` gives you a single view of all recent activity across your organization.
- Deep workflow intelligence. You can check the full scope of any process using `list_workflow_jobs` and understand which components feed into the final build.

## How It Works

The bottom line is that you keep all your CI/CD control within your existing chat interface, eliminating context switching between dashboards.

1. Subscribe to this MCP and obtain your CircleCI Personal API Token from your user settings.
2. Provide the token to your AI client through Vinkius. This authorizes your agent to interact with your pipelines.
3. Ask your agent a natural language question, like 'What's the status of the staging deployment?' The agent executes the necessary tools and reports the findings.

## Frequently Asked Questions

**How can I use the CircleCI MCP for AI Agents to check build status?**
You simply ask your agent for a summary of recent builds or a specific job's status. The agent uses the necessary tools to pull up the details, giving you an instant report without needing to open the dashboard.

**Does CircleCI MCP allow me to trigger manual deployments?**
Yes. You can tell your agent to start a new pipeline for any project or branch. This is useful for hotfixes when you need an immediate, controlled deployment run.

**Can I find out what environment variables are used across my projects?**
Absolutely. By asking the MCP to list shared contexts, your agent retrieves a complete inventory of all defined environment variables for your entire organization, which is critical for security and auditing.

**What if I need details on a specific job that failed?**
You can tell the agent about the failing job ID or workflow. It will use the available tools to pull detailed execution metadata, allowing you to pinpoint exactly where and why the code broke.

**Is CircleCI MCP useful for new developers joining the team?**
Yes. New hires can ask the agent to list all current workflows or retrieve their user profile information, giving them immediate context on how the company's pipelines are structured and managed.