CircleCI
CircleCI is a continuous integration and delivery platform that automates build, test, and deployment pipelines for software development.
Verdict
Common use cases
- Surface failed jobs from last night's deploy
- Download build artifacts for QA review
- Check test metadata for flaky spec files
- List recent pipelines during sprint retrospectives
- Audit self-hosted runner availability
Integration
- Vendor
- CircleCI
- Category
- developer-tools
- Auth
- API_KEY
- Tools
- 9
- Composio slug
circleci
Tools
- Get Job Artifacts
Tool to retrieve artifacts produced by a specific job. use after a job has completed to list its output files.
- Get Job Details
Tool to fetch details of a specific job within a project. use when you need status, timing, and executor information for a circleci job by its number.
- Get Pipeline Config
Tool to fetch pipeline configuration by id. use when you need the source or compiled yaml of a specific pipeline.
- Get Test Metadata
Tool to fetch test metadata for a specific job. use when you need detailed test results, run times, and failure messages after a job completes.
- Get User Information
Tool to retrieve information about a circleci user by their unique id. use when you need user profile details after obtaining the user id.
- List Pipelines for Project
Tool to list all pipelines for a specific project. use when you need to retrieve the pipelines for a project (e.g., to display recent runs on a dashboard).
- List Self-Hosted Runners
Tool to list available self-hosted runners. use when you need to retrieve all configured self-hosted runners for your organization.
- List Workflows by Pipeline ID
Tool to list all workflows associated with a specific pipeline. use when you need to fetch or paginate through workflows by pipeline id.
- Trigger Pipeline
Tool to trigger a new pipeline for the specified project. use when you need to start a build on a branch or tag programmatically.
Setup
Setup guide
- 11. In Switchy, open your workspace settings and navigate to the MCP Integrations page. 2. Click 'Add Integration' and select CircleCI from the developer tools category. 3. Open CircleCI in a new tab, go to User Settings → Personal API Tokens, and generate a token with read scope for projects, pipelines, and workflows. 4. Paste the token into Switchy's auth field and click Connect. 5. Return to any Space, type '@CircleCI get user information' and send — if the MCP replies with your CircleCI profile, the connection is live. 6. To invoke a tool, @mention CircleCI followed by the command and required parameters (e.g., '@CircleCI list pipelines for project my-org/my-repo').
What teammates see: by default, memories from CircleCI are scoped to the Space (PROJECT visibility) - you can mark any memory PRIVATE or share it ORG-wide.
Works well with
Top models
Compatibility data appears once enough Spaces have used this MCP together with a given model.
How Switchy teams use it
Starter prompts
Check Recent Pipeline Status
@CircleCI list pipelines for project my-org/my-repo and show me the status of the last five runsOpen in a Space →
Investigate Failed Job
@CircleCI get job details for project my-org/my-repo job number 1234, then retrieve test metadata to show which tests failedOpen in a Space →
Download Build Artifacts
@CircleCI get job artifacts for project my-org/my-repo job number 5678 and list all available filesOpen in a Space →
Review Pipeline Config
@CircleCI get pipeline config for pipeline ID abc-123-def and show me the compiled configurationOpen in a Space →
Audit Self-Hosted Runners
@CircleCI list self-hosted runners and show me their resource class and current statusOpen in a Space →
Example outputs
Illustrative - representative of the model's voice and quality, not literal recordings.
@circleci show me the last 5 pipelines for our api-service repo and their status
Here are the last 5 pipelines for api-service: 1. Pipeline #847 (main) - SUCCESS - triggered 2 hours ago by deploy-bot 2. Pipeline #846 (feature/auth-v2) - FAILED - triggered 4 hours ago by sarah.chen 3. Pipeline #845 (main) - SUCCESS - triggered 6 hours ago by github-webhook 4. Pipeline #844 (hotfix/rate-limit) - SUCCESS - triggered 8 hours ago by mike.torres 5. Pipeline #843 (main) - RUNNING - triggered 9 hours ago by scheduled-job Pipeline #846 failed during the test-suite workflow. Would you like me to pull the test metadata to see which tests broke?
This example shows the MCP's read capability for pipeline history. Requires a valid CircleCI API token with project-level read access. The MCP returns structured data that the AI formats into a readable summary. Useful for quick status checks without opening the CircleCI dashboard.
@circleci get the test results from pipeline #846 and tell me which tests failed
Pipeline #846 ran 247 tests across 3 jobs. Here are the 4 failures: **test-suite job:** - `AuthServiceTest.testTokenRefresh` - AssertionError: expected 200, got 401 (runtime: 1.2s) - `AuthServiceTest.testExpiredTokenHandling` - NullPointerException at line 89 (runtime: 0.8s) - `RateLimiterTest.testBurstCapacity` - Timeout after 30s **integration-tests job:** - `E2EAuthFlow.testMultiFactorLogin` - Connection refused to mock-idp:8080 (runtime: 5.1s) All failures occurred in the auth-v2 feature branch. The token refresh logic appears to be the root cause affecting multiple test cases.
Demonstrates the MCP's ability to fetch detailed test metadata after a job completes. The AI can parse failure messages and identify patterns across test runs. Note that test metadata is only available for jobs that have finished executing — you cannot query in-progress tests.
@circleci compare the artifacts from job #3401 and #3389 to see what changed in the build output
Comparing artifacts between job #3401 (current) and #3389 (baseline): **Job #3401 artifacts (6 files, 142 MB total):** - api-service.jar (89 MB) - coverage-report.html (2.1 MB) - test-results.xml (450 KB) - dependency-tree.txt (89 KB) - build-logs.txt (1.2 MB) - performance-profile.json (340 KB) **Job #3389 artifacts (5 files, 128 MB total):** - api-service.jar (78 MB) ← 11 MB larger now - coverage-report.html (2.0 MB) - test-results.xml (420 KB) - dependency-tree.txt (85 KB) - build-logs.txt (1.1 MB) The JAR grew by 14% and a new performance-profile.json artifact appeared in #3401. This suggests new dependencies or profiling instrumentation was added between these builds.
Shows how the MCP can retrieve artifact lists for comparative analysis. The AI synthesizes differences but cannot download or diff file contents directly — it works with metadata only (filenames, sizes, timestamps). Useful for tracking build bloat or identifying when new outputs appear in your pipeline.
Use-case deep-dives
When CircleCI MCP speeds up incident triage
A 6-person engineering team ships to staging twice daily and needs to confirm build artifacts match the expected bundle size before promoting to production. The CircleCI MCP lets them query job artifacts and test metadata directly in Switchy without context-switching to the CircleCI dashboard. During a Thursday deploy, the team notices a 40% bundle size spike—they pull test metadata and artifact logs in one thread, identify the culprit commit, and roll back in under 10 minutes. This works cleanly for teams running under 50 pipelines per day; beyond that threshold, you'll want dedicated monitoring instead of ad-hoc MCP queries. If your deploy cadence is daily or less and you need fast artifact inspection during standups or incidents, this MCP cuts the lookup time in half.
Why support teams skip this MCP for now
A 3-person customer success team occasionally needs to confirm whether a customer's feature request shipped in the latest release. They want to search pipeline history by branch name or commit message to verify deploy status. The CircleCI MCP doesn't expose full-text search across pipeline configs or commit metadata—it requires you to already know the pipeline ID or project slug. For this scenario, the team is better off bookmarking the CircleCI web UI or using a Slack integration that posts deploy summaries automatically. The MCP shines when engineers already have pipeline IDs from logs or monitoring tools and need to drill into job details or artifacts. If your support workflow starts with vague questions like 'did feature X ship?', this MCP won't close the loop without manual ID hunting first.
When this MCP helps DevOps audit runner usage
A 4-person platform team manages 12 self-hosted CircleCI runners across AWS and wants to audit which runners are idle versus oversubscribed during peak hours. The CircleCI MCP's List Self-Hosted Runners tool surfaces runner status and metadata in Switchy, letting the team cross-reference runner IDs with recent pipeline logs to identify bottlenecks. During a quarterly capacity review, they discover 3 runners handling 80% of the load while 5 sit unused—they rebalance tags and save $400/month in EC2 costs. This scenario assumes your team already tracks pipeline volume in another tool (Datadog, CloudWatch) and just needs the runner inventory to complete the picture. If you're running fewer than 5 self-hosted runners or only check capacity once a quarter, the web UI is sufficient and this MCP is overkill.
Frequently asked
What does the CircleCI MCP let me do in Switchy?
It pulls build data from your CircleCI projects — job status, test results, artifacts, pipeline configs, and runner info. You can ask Switchy to check why a build failed, compare test run times across jobs, or list recent pipelines without opening the CircleCI dashboard. It's read-only; you can't trigger builds or change configs through the MCP.
Do I need admin access to connect CircleCI?
No, but you do need a CircleCI API token with read permissions for the projects you want to query. Generate a personal API token in your CircleCI user settings, then paste it into Switchy. If your org restricts token creation, ask an admin to create one with project-level read scope and share it with your team.
Can the CircleCI MCP trigger new builds or cancel running jobs?
No. The MCP only reads data — job details, test metadata, artifacts, pipeline configs. If you need to trigger or cancel builds, use CircleCI's web UI or their full REST API directly. This MCP is designed for monitoring and debugging, not orchestration.
Why use this instead of just opening CircleCI in a browser tab?
You can ask Switchy natural-language questions like "which test failed in the last deploy" or "show me artifacts from job 1234" without clicking through the CircleCI UI. It's faster for one-off queries and lets you combine CircleCI data with other tools in the same conversation — for example, checking a build failure then opening the relevant GitHub PR.
Who on my team should connect the CircleCI integration?
Anyone who needs to debug builds or review test results. Each person connects their own API token, so access mirrors their CircleCI permissions. If you share a single token across the team, everyone sees the same projects. The MCP doesn't count against CircleCI's user seats or API rate limits beyond normal token usage.