{"id":27391516,"url":"https://github.com/circleci-public/mcp-server-circleci","last_synced_at":"2025-04-13T20:56:12.800Z","repository":{"id":286176332,"uuid":"955501958","full_name":"CircleCI-Public/mcp-server-circleci","owner":"CircleCI-Public","description":"A specialized server implementation for the Model Context Protocol (MCP) designed to integrate with CircleCI's development workflow. This project serves as a bridge between CircleCI's infrastructure and the Model Context Protocol, enabling enhanced AI-powered development experiences.","archived":false,"fork":false,"pushed_at":"2025-04-11T21:02:23.000Z","size":308,"stargazers_count":10,"open_issues_count":5,"forks_count":3,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-13T20:55:58.126Z","etag":null,"topics":["mcp-server","modelcontextprotocol"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CircleCI-Public.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-26T18:31:55.000Z","updated_at":"2025-04-11T19:15:32.000Z","dependencies_parsed_at":"2025-04-04T19:48:18.233Z","dependency_job_id":"6c99353b-9400-48ad-a2a5-92e59284b55e","html_url":"https://github.com/CircleCI-Public/mcp-server-circleci","commit_stats":null,"previous_names":["circleci-public/mcp-server-circleci"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircleCI-Public%2Fmcp-server-circleci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircleCI-Public%2Fmcp-server-circleci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircleCI-Public%2Fmcp-server-circleci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircleCI-Public%2Fmcp-server-circleci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CircleCI-Public","download_url":"https://codeload.github.com/CircleCI-Public/mcp-server-circleci/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248782280,"owners_count":21160716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp-server","modelcontextprotocol"],"created_at":"2025-04-13T20:56:08.192Z","updated_at":"2025-04-13T20:56:12.794Z","avatar_url":"https://github.com/CircleCI-Public.png","language":"TypeScript","funding_links":[],"categories":["Developer Tools"],"sub_categories":["How to Submit"],"readme":"# CircleCI MCP Server\n\n[![GitHub](https://img.shields.io/github/license/CircleCI-Public/mcp-server-circleci)](https://github.com/CircleCI-Public/mcp-server-circleci/blob/main/LICENSE)\n[![CircleCI](https://dl.circleci.com/status-badge/img/gh/CircleCI-Public/mcp-server-circleci/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/CircleCI-Public/mcp-server-circleci/tree/main)\n[![npm](https://img.shields.io/npm/v/@circleci/mcp-server-circleci?logo=npm)](https://www.npmjs.com/package/@circleci/mcp-server-circleci)\n\nModel Context Protocol (MCP) is a [new, standardized protocol](https://modelcontextprotocol.io/introduction) for managing context between large language models (LLMs) and external systems. In this repository, we provide an MCP Server for [CircleCI](https://circleci.com).\n\nThis lets you use Cursor IDE, or any MCP Client, to use natural language to accomplish things with CircleCI, e.g.:\n\n- `Find the latest failed pipeline on my branch and get logs`\n  https://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide\n\nhttps://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74\n\n## Requirements\n\n- pnpm package manager - [Learn more](https://pnpm.io/installation)\n- Node.js \u003e= v18.0.0\n- CircleCI API token - you can generate one through the CircleCI. [Learn more](https://circleci.com/docs/managing-api-tokens/) or [click here](https://app.circleci.com/settings/user/tokens) for quick access.\n\n## Installation\n\n### Cursor\n\nAdd the following to your cursor MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"circleci-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@circleci/mcp-server-circleci\"],\n      \"env\": {\n        \"CIRCLECI_TOKEN\": \"your-circleci-token\",\n        \"CIRCLECI_BASE_URL\": \"https://circleci.com\" // Optional - required for on-prem customers only\n      }\n    }\n  }\n}\n```\n\nSee the guide below for more information on using MCP servers with cursor:\nhttps://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers\n\n### Claude Desktop\n\nAdd the following to your claude_desktop_config.json:\n\n```json\n{\n  \"mcpServers\": {\n    \"circleci-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@circleci/mcp-server-circleci\"],\n      \"env\": {\n        \"CIRCLECI_TOKEN\": \"your-circleci-token\",\n        \"CIRCLECI_BASE_URL\": \"https://circleci.com\" // Optional - required for on-prem customers only\n      }\n    }\n  }\n}\n```\n\nTo find/create this file, first open your claude desktop settings. Then click on \"Developer\" in the left-hand bar of the Settings pane, and then click on \"Edit Config\"\n\nThis will create a configuration file at:\n\n- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\n- Windows: %APPDATA%\\Claude\\claude_desktop_config.json\n\n### VS Code\n\nAdd the MCP server to your settings.json under `mcp -\u003e servers`:\n\n```json\n\"circleci-mcp-server\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@circleci/mcp-server-circleci\"],\n  \"env\": {\n    \"CIRCLECI_TOKEN\": \"your-circleci-token\",\n    \"CIRCLECI_BASE_URL\": \"https://circleci.com\" // Optional - required for on-prem customers only\n  }\n}\n```\n\nSee the guide below for more information on using MCP servers with VS Code:\nhttps://code.visualstudio.com/docs/copilot/chat/mcp-servers\n\n### Windsurf\n\nAdd the following to your windsurf mcp_config.json:\n\n```json\n{\n  \"mcpServers\": {\n    \"circleci-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@circleci/mcp-server-circleci\"],\n      \"env\": {\n        \"CIRCLECI_TOKEN\": \"your-circleci-token\",\n        \"CIRCLECI_BASE_URL\": \"https://circleci.com\" // Optional - required for on-prem customers only\n      }\n    }\n  }\n}\n```\n\nSee the guide below for more information on using MCP servers with windsurf:\nhttps://docs.windsurf.com/windsurf/mcp\n\n# Features\n\n## Supported Tools\n\n- `get_build_failure_logs`\n\n  Retrieves detailed failure logs from CircleCI builds. This tool can be used in two ways:\n\n  1. Using CircleCI URLs:\n\n     - Provide a failed job URL or pipeline URL directly\n     - Example: \"Get logs from https://app.circleci.com/pipelines/github/org/repo/123\"\n\n  2. Using Local Project Context:\n     - Works from your local workspace by providing:\n       - Workspace root path\n       - Git remote URL\n       - Branch name\n     - Example: \"Find the latest failed pipeline on my current branch\"\n\n  The tool returns formatted logs including:\n\n  - Job names\n  - Step-by-step execution details\n  - Failure messages and context\n\n  This is particularly useful for:\n\n  - Debugging failed builds\n  - Analyzing test failures\n  - Investigating deployment issues\n  - Quick access to build logs without leaving your IDE\n\n- `find_flaky_tests`\n\n  Identifies flaky tests in your CircleCI project by analyzing test execution history. This leverages the flaky test detection feature described here: https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detection\n  \n  This tool can be used in two ways:\n\n  1. Using CircleCI Project URL:\n     - Provide the project URL directly from CircleCI\n     - Example: \"Find flaky tests in https://app.circleci.com/pipelines/github/org/repo\"\n\n  2. Using Local Project Context:\n     - Works from your local workspace by providing:\n       - Workspace root path\n       - Git remote URL\n     - Example: \"Find flaky tests in my current project\"\n\n  The tool returns detailed information about flaky tests, including:\n\n  - Test names and file locations\n  - Failure messages and contexts\n\n  This helps you:\n  - Identify unreliable tests in your test suite\n  - Get detailed context about test failures\n  - Make data-driven decisions about test improvements\n\n# Development\n\n## Getting Started\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/CircleCI-Public/mcp-server-circleci.git\n   cd mcp-server-circleci\n   ```\n\n2. Install dependencies:\n\n   ```bash\n   pnpm install\n   ```\n\n3. Build the project:\n   ```bash\n   pnpm build\n   ```\n\n## Development with MCP Inspector\n\nThe easiest way to iterate on the MCP Server is using the MCP inspector. You can learn more about the MCP inspector at https://modelcontextprotocol.io/docs/tools/inspector\n\n1. Start the development server:\n\n   ```bash\n   pnpm watch # Keep this running in one terminal\n   ```\n\n2. In a separate terminal, launch the inspector:\n\n   ```bash\n   pnpm inspector\n   ```\n\n3. Configure the environment:\n   - Add your `CIRCLECI_TOKEN` to the Environment Variables section in the inspector UI\n   - The token needs read access to your CircleCI projects\n   - Optionally you can set your CircleCI Base URL. Defaults to `https//circleci.com`\n\n## Testing\n\n- Run the test suite:\n\n  ```bash\n  pnpm test\n  ```\n\n- Run tests in watch mode during development:\n  ```bash\n  pnpm test:watch\n  ```\n\nFor more detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcircleci-public%2Fmcp-server-circleci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcircleci-public%2Fmcp-server-circleci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcircleci-public%2Fmcp-server-circleci/lists"}