# CircleCI MCP MCP

> CircleCI MCP connects your build system and deployment pipelines to any AI agent. You can query, monitor, or manually trigger software builds—getting detailed status reports on workflows, jobs, and environments without opening a dashboard.

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

## Description

This connector gives you full control over complex CI/CD processes through natural conversation. Instead of logging into the CircleCI dashboard, your agent handles everything from checking the health of last week's release to manually initiating an emergency build for a specific branch.

Need to know why a deployment failed? You can list recent pipelines and check detailed job metadata instantly. The system tracks shared environment contexts used across projects, so you always have visibility into where sensitive data is being secured during the process. Because complex deployments often require actions in multiple systems—say, checking build status then updating Jira tickets—you can chain this MCP with other services via Vinkius. This means your agent doesn't just read statuses; it builds an automated sequence of steps across platforms using a single connection point.

Your AI client handles the heavy lifting: listing workflows inside a pipeline or pulling up user profile details to confirm who initiated the last run. It’s all about getting accurate, immediate system status without the manual clicks.

## Tools

### get_job_details
Provides detailed information for a specific job within a workflow run.

### get_my_cci_profile
Retrieves basic identity and membership information about the authenticated user.

### get_workflow_details
Gathers detailed structural information for a specific workflow definition.

### list_cci_contexts
Lists all shared environment contexts used by the organization for securing data.

### list_cci_pipelines
Retrieves a list of recent and active CI/CD pipelines across various projects.

### list_pipeline_workflows
Shows all the specific workflows that exist within one given pipeline run.

### list_workflow_jobs
Lists every individual job associated with a specified workflow.

### trigger_cci_pipeline
Initiates a brand new pipeline run for an entire project, specifying the branch and target.

## Prompt Examples

**Prompt:** 
```
List my last 5 pipelines in CircleCI.
```

**Response:** 
```
Retrieving your recent pipelines... I found 5 items across your projects. 4 were successful and 1 for 'web-app' failed. Would you like to see the workflows for the failed pipeline?
```

**Prompt:** 
```
Trigger a new pipeline for project 'gh/acme/api' on the 'main' branch.
```

**Response:** 
```
Triggering pipeline for gh/acme/api (branch: main)... The run has been successfully started. The new pipeline ID is '550e8400-e29b-41d4-a716-446655440000'.
```

**Prompt:** 
```
Show me the status of all jobs in workflow ID 'wf-12345'.
```

**Response:** 
```
Checking workflow wf-12345... This workflow has 3 jobs: 'build' (Success), 'test' (Success), and 'deploy' (On Hold). The deploy job is waiting for manual approval.
```

## Capabilities

### Check Build History
List and retrieve detailed information about recent CI/CD pipelines across your accounts.

### Start New Builds
Manually trigger a new pipeline run for any specific project or branch immediately.

### View Workflow Details
Access detailed structure and status information for entire workflows, including all associated jobs.

### Examine Job Statuses
Get deep metadata and execution status reports for specific, individual jobs within a workflow.

### Audit Project Contexts
List shared environment contexts used across your organization to manage sensitive project data.

## Use Cases

### Urgent Hotfix Required
A developer sees a production bug. Instead of manually navigating to the build page, they tell their agent: 'I need a hotfix run for the main branch.' The agent uses `trigger_cci_pipeline` and reports back the new pipeline ID immediately.

### Pre-release Audit
A Release Manager needs to confirm all necessary stages passed. They ask the agent to list recent pipelines, using `list_cci_pipelines`, confirming that not only did the build succeed but also the specific 'security scan' job reported a passing status.

### Debugging Workflow Breakage
A workflow runs but stops prematurely. The engineer asks the agent to check `list_workflow_jobs` for that pipeline, revealing which specific job (`get_job_details`) timed out and providing the exact error log.

### Checking User Permissions
Before running a sensitive deployment, you ask your agent to use `get_my_cci_profile` to verify that your current user account still has the required organization membership rights for the target project.

## Benefits

- Check build status instantly: Use `list_cci_pipelines` to see the success or failure of your latest deployment without logging into a separate web dashboard. You know exactly where things stand, right here in your chat.
- Control deployments on demand: Need to fix an issue? Running `trigger_cci_pipeline` allows you to manually start a new pipeline for a specific project and branch with simple conversation prompts.
- Deep visibility into failures: If a job fails, don't just see 'Failed.' Use the agent to query `get_job_details` to pull deep metadata on why that single step broke. You get actionable logs right away.
- Understand system structure: Before debugging, use `list_cci_contexts` to list shared environments. This helps you confirm which set of variables your deployment process is actually using for sensitive data.
- Track dependencies easily: If a pipeline has multiple stages, calling the agent to look up `list_pipeline_workflows` shows you the entire dependency map—which jobs rely on which other components.

## How It Works

The bottom line is that you treat complex CI/CD operations like talking to a colleague—you just ask, and the system provides the actionable answer.

1. Subscribe to this MCP and provide your CircleCI Personal API Token.
2. Connect the token through your AI client (like Cursor or Claude).
3. Ask your agent a natural language question, such as 'Show me the status of my latest deployment job,' and get instant results.

## Frequently Asked Questions

**How do I check recent pipelines using list_cci_pipelines?**
You simply ask your agent to 'List my last 10 pipelines.' The MCP handles the call, and you get a summary of all projects' build statuses immediately.

**Can I manually trigger a pipeline using trigger_cci_pipeline?**
Yes. You tell your agent to 'Trigger a new run for the web-app on the main branch.' The MCP executes this action and gives you the brand new pipeline ID.

**What is the difference between list_cci_pipelines and get_workflow_details?**
`list_cci_pipelines` gives a high-level view of runs over time. `get_workflow_details` dives deep into the structure—it shows you exactly how one single workflow is defined with its internal jobs.

**How do I find out what contexts are available? (list_cci_contexts)**
Use `list_cci_contexts`. It will list all shared environment variables and data containers your organization has set up, helping you understand the scope of variables used by builds.

**What information can I get about a specific job run using `get_job_details`?**
You retrieve detailed status and metadata for any single job execution. This includes seeing the exact exit code, resource usage metrics, and logs that pinpoint why a build failed or succeeded.

**How do I map out all jobs within a specific workflow using `list_workflow_jobs`?**
Running `list_workflow_jobs` returns an exhaustive list of every job defined in a workflow. This lets you check the full scope of the pipeline without needing to trigger or wait for it to run.

**I need to verify my user identity and organization role; what does `get_my_cci_profile` do?**
This tool fetches your authenticated user profile details. It confirms who you are, shows your organizational membership, and provides context on the scope of data available to your agent.

**If I know my pipeline ID, how do I find all associated workflows using `list_pipeline_workflows`?**
By calling `list_pipeline_workflows`, you get a list of every workflow that belongs beneath a specific pipeline. This is the first step in understanding the full structural map of your CI/CD process.