Skip to content
Back to search

mcp-server-circleci

[DEPRECATED] This package is no longer maintained. Migrate to CircleCI's hosted MCP server or the CircleCI CLI MCP. See https://circleci.com/docs/guides/toolkit/circleci-mcp-overview/

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/circleci-public--mcp-server-circleci/badge.svg)](/listings/circleci-public--mcp-server-circleci)

HTML

<a href="/listings/circleci-public--mcp-server-circleci"><img src="/api/listings/circleci-public--mcp-server-circleci/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **Team / centralized deployment:** To run one shared remote server for your org (Kubernetes, Docker, etc.) with per-developer or shared CircleCI tokens, see [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server).

<details> <summary><strong>Cursor</strong></summary>

**Prerequisites:** - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/)) - NPX: [Node.js >= v18](https://nodejs.org/) and [pnpm](https://pnpm.io/installation) - Docker: [Docker](https://docs.docker.com/get-docker/)

Using NPX in a local MCP Server

Add the following to your Cursor MCP config:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

> `CIRCLECI_BASE_URL` is optional — required for on-prem customers only. > `MAX_MCP_OUTPUT_LENGTH` is optional — maximum output length for MCP responses (default: 50000).

Using Docker in a local MCP Server

Add the following to your Cursor MCP config:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Using a Self-Managed Remote MCP Server

See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use the [per-user client configuration](#client-configuration-per-user-tokens) and add it to your Cursor MCP config (`Cursor Settings → MCP`).

</details>

<details> <summary><strong>VS Code</strong></summary>

**Prerequisites:** - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/)) - NPX: [Node.js >= v18](https://nodejs.org/) and [pnpm](https://pnpm.io/installation) - Docker: [Docker](https://docs.docker.com/get-docker/)

Using NPX in a local MCP Server

Add the following to `.vscode/mcp.json` in your project:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

> 💡 Inputs are prompted on first server start, then stored securely by VS Code.

Using Docker in a local MCP Server

Add the following to `.vscode/mcp.json` in your project:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,128 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. > [!IMPORTANT]
  2. > **This package is deprecated. Please migrate.**
  3. >
  4. > `@circleci/mcp-server-circleci` is no longer receiving feature work. Use CircleCI's **hosted MCP server** or the **CircleCI CLI MCP** instead — see the **[CircleCI MCP overview](https://circleci.com/docs/guides/toolkit/circleci-mcp-overview/)**.
  5. >
  6. > This repository will be archived. Existing versions remain installable from npm, but running an unmaintained server that holds a CircleCI Personal API Token is not recommended.
  7. >
  8. > If you are running the **self-managed remote transport** (`start=remote`), migrate first: the hosted server is its direct replacement and removes the need to operate a network-facing service that brokers your org's token.
  9. # CircleCI MCP Server
  10. [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/CircleCI-Public/mcp-server-circleci/blob/main/LICENSE)
  11. [![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)
  12. [![npm](https://img.shields.io/npm/v/@circleci/mcp-server-circleci?logo=npm)](https://www.npmjs.com/package/@circleci/mcp-server-circleci)
  13. Model 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).
  14. Use Cursor, Windsurf, Copilot, Claude, or any MCP-compatible client to interact with CircleCI using natural language — without leaving your IDE.
  15. ## Tools
  16. | Tool | Description |
  17. |------|-------------|
  18. | [`config_helper`](#config_helper) | Validate and get guidance for your CircleCI configuration |
  19. | [`download_usage_api_data`](#download_usage_api_data) | Download usage data from the CircleCI Usage API |
  20. | [`find_flaky_tests`](#find_flaky_tests) | Identify flaky tests by analyzing test execution history |
  21. | [`find_underused_resource_classes`](#find_underused_resource_classes) | Find jobs with underused compute resources |
  22. | [`get_build_failure_logs`](#get_build_failure_logs) | Retrieve detailed failure logs from CircleCI builds |
  23. | [`get_job_test_results`](#get_job_test_results) | Retrieve test metadata and results for CircleCI jobs |
  24. | [`get_latest_pipeline_status`](#get_latest_pipeline_status) | Get the status of the latest pipeline for a branch |
  25. | [`list_artifacts`](#list_artifacts) | List artifacts produced by a CircleCI job |
  26. | [`list_component_versions`](#list_component_versions) | List all versions for a CircleCI component |
  27. | [`list_followed_projects`](#list_followed_projects) | List all CircleCI projects you're following |
  28. | [`rerun_workflow`](#rerun_workflow) | Rerun a workflow from start or from the failed job |
  29. | [`run_pipeline`](#run_pipeline) | Trigger a pipeline to run |
  30. | [`run_rollback_pipeline`](#run_rollback_pipeline) | Trigger a rollback for a project |
  31. ## Installation
  32. > **Team / centralized deployment:** To run one shared remote server for your org (Kubernetes, Docker, etc.) with per-developer or shared CircleCI tokens, see [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server).
  33. <details>
  34. <summary><strong>Cursor</strong></summary>
  35. **Prerequisites:**
  36. - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/))
  37. - NPX: [Node.js](https://nodejs.org/) `^22.23.4 || ^24.22.1 || >=26.12.1` and [pnpm](https://pnpm.io/installation)
  38. - Docker: [Docker](https://docs.docker.com/get-docker/)
  39. #### Using NPX in a local MCP Server
  40. Add the following to your Cursor MCP config:
  41. ```json
  42. {
  43. "mcpServers": {
  44. "circleci-mcp-server": {
  45. "command": "npx",
  46. "args": ["-y", "@circleci/mcp-server-circleci@latest"],
  47. "env": {
  48. "CIRCLECI_TOKEN": "your-circleci-token",
  49. "CIRCLECI_BASE_URL": "https://circleci.com",
  50. "MAX_MCP_OUTPUT_LENGTH": "50000"
  51. }
  52. }
  53. }
  54. }
  55. ```
  56. > `CIRCLECI_BASE_URL` is optional — required for on-prem customers only.
  57. > `MAX_MCP_OUTPUT_LENGTH` is optional — maximum output length for MCP responses (default: 50000).
  58. #### Using Docker in a local MCP Server
  59. Add the following to your Cursor MCP config:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "circleci-mcp-server": {
  64. "command": "docker",
  65. "args": [
  66. "run",
  67. "--rm",
  68. "-i",
  69. "-e",
  70. "CIRCLECI_TOKEN",
  71. "-e",
  72. "CIRCLECI_BASE_URL",
  73. "-e",
  74. "MAX_MCP_OUTPUT_LENGTH",
  75. "circleci/mcp-server-circleci"
  76. ],
  77. "env": {
  78. "CIRCLECI_TOKEN": "your-circleci-token",
  79. "CIRCLECI_BASE_URL": "https://circleci.com",
  80. "MAX_MCP_OUTPUT_LENGTH": "50000"
  81. }
  82. }
  83. }
  84. }
  85. ```
  86. #### Using a Self-Managed Remote MCP Server
  87. See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use the [per-user client configuration](#client-configuration-per-user-tokens) and add it to your Cursor MCP config (`Cursor Settings → MCP`).
  88. </details>
  89. <details>
  90. <summary><strong>VS Code</strong></summary>
  91. **Prerequisites:**
  92. - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/))
  93. - NPX: [Node.js](https://nodejs.org/) `^22.23.4 || ^24.22.1 || >=26.12.1` and [pnpm](https://pnpm.io/installation)
  94. - Docker: [Docker](https://docs.docker.com/get-docker/)
  95. #### Using NPX in a local MCP Server
  96. Add the following to `.vscode/mcp.json` in your project:
  97. ```json
  98. {
  99. "inputs": [
  100. {
  101. "type": "promptString",
  102. "id": "circleci-token",
  103. "description": "CircleCI API Token",
  104. "password": true
  105. },
  106. {
  107. "type": "promptString",
  108. "id": "circleci-base-url",
  109. "description": "CircleCI Base URL",
  110. "default": "https://circleci.com"
  111. }
  112. ],
  113. "servers": {
  114. "circleci-mcp-server": {
  115. "type": "stdio",
  116. "command": "npx",
  117. "args": ["-y", "@circleci/mcp-server-circleci@latest"],
  118. "env": {
  119. "CIRCLECI_TOKEN": "${input:circleci-token}",
  120. "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
  121. }
  122. }
  123. }
  124. }
  125. ```
  126. > 💡 Inputs are prompted on first server start, then stored securely by VS Code.
  127. #### Using Docker in a local MCP Server
  128. Add the following to `.vscode/mcp.json` in your project:
  129. ```json
  130. {
  131. "inputs": [
  132. {
  133. "type": "promptString",
  134. "id": "circleci-token",
  135. "description": "CircleCI API Token",
  136. "password": true
  137. },
  138. {
  139. "type": "promptString",
  140. "id": "circleci-base-url",
  141. "description": "CircleCI Base URL",
  142. "default": "https://circleci.com"
  143. }
  144. ],
  145. "servers": {
  146. "circleci-mcp-server": {
  147. "type": "stdio",
  148. "command": "docker",
  149. "args": [
  150. "run",
  151. "--rm",
  152. "-i",
  153. "-e",
  154. "CIRCLECI_TOKEN",
  155. "-e",
  156. "CIRCLECI_BASE_URL",
  157. "circleci/mcp-server-circleci"
  158. ],
  159. "env": {
  160. "CIRCLECI_TOKEN": "${input:circleci-token}",
  161. "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
  162. }
  163. }
  164. }
  165. }
  166. ```
  167. #### Using a Self-Managed Remote MCP Server
  168. See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use the [per-user client configuration](#client-configuration-per-user-tokens) in `.vscode/mcp.json`.
  169. </details>
  170. <details>
  171. <summary><strong>Claude Desktop</strong></summary>
  172. **Prerequisites:**
  173. - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/))
  174. - NPX: [Node.js](https://nodejs.org/) `^22.23.4 || ^24.22.1 || >=26.12.1` and [pnpm](https://pnpm.io/installation)
  175. - Docker: [Docker](https://docs.docker.com/get-docker/)
  176. #### Using NPX in a local MCP Server
  177. Add the following to your `claude_desktop_config.json`:
  178. ```json
  179. {
  180. "mcpServers": {
  181. "circleci-mcp-server": {
  182. "command": "npx",
  183. "args": ["-y", "@circleci/mcp-server-circleci@latest"],
  184. "env": {
  185. "CIRCLECI_TOKEN": "your-circleci-token",
  186. "CIRCLECI_BASE_URL": "https://circleci.com",
  187. "MAX_MCP_OUTPUT_LENGTH": "50000"
  188. }
  189. }
  190. }
  191. }
  192. ```
  193. #### Using Docker in a local MCP Server
  194. Add the following to your `claude_desktop_config.json`:
  195. ```json
  196. {
  197. "mcpServers": {
  198. "circleci-mcp-server": {
  199. "command": "docker",
  200. "args": [
  201. "run",
  202. "--rm",
  203. "-i",
  204. "-e",
  205. "CIRCLECI_TOKEN",
  206. "-e",
  207. "CIRCLECI_BASE_URL",
  208. "-e",
  209. "MAX_MCP_OUTPUT_LENGTH",
  210. "circleci/mcp-server-circleci"
  211. ],
  212. "env": {
  213. "CIRCLECI_TOKEN": "your-circleci-token",
  214. "CIRCLECI_BASE_URL": "https://circleci.com",
  215. "MAX_MCP_OUTPUT_LENGTH": "50000"
  216. }
  217. }
  218. }
  219. }
  220. ```
  221. #### Using a Self-Managed Remote MCP Server
  222. See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Create a wrapper script as shown in [Claude Desktop and CLI clients](#claude-desktop-and-cli-clients), then point your `claude_desktop_config.json` at it.
  223. To find or create your config file, open Claude Desktop settings, click **Developer** in the left sidebar, then click **Edit Config**. The config file is located at:
  224. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  225. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  226. For more information: https://modelcontextprotocol.io/quickstart/user
  227. </details>
  228. <details>
  229. <summary><strong>Claude Code</strong></summary>
  230. **Prerequisites:**
  231. - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/))
  232. - NPX: [Node.js](https://nodejs.org/) `^22.23.4 || ^24.22.1 || >=26.12.1` and [pnpm](https://pnpm.io/installation)
  233. - Docker: [Docker](https://docs.docker.com/get-docker/)
  234. #### Using NPX in a local MCP Server
  235. ```bash
  236. claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest
  237. ```
  238. #### Using Docker in a local MCP Server
  239. ```bash
  240. claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com -- docker run --rm -i -e CIRCLECI_TOKEN -e CIRCLECI_BASE_URL circleci/mcp-server-circleci
  241. ```
  242. #### Using a Self-Managed Remote MCP Server
  243. See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server) and the [Claude Code](#claude-code) client setup there.
  244. </details>
  245. <details>
  246. <summary><strong>Windsurf</strong></summary>
  247. **Prerequisites:**
  248. - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/))
  249. - NPX: [Node.js](https://nodejs.org/) `^22.23.4 || ^24.22.1 || >=26.12.1` and [pnpm](https://pnpm.io/installation)
  250. - Docker: [Docker](https://docs.docker.com/get-docker/)
  251. #### Using NPX in a local MCP Server
  252. Add the following to your Windsurf `mcp_config.json`:
  253. ```json
  254. {
  255. "mcpServers": {
  256. "circleci-mcp-server": {
  257. "command": "npx",
  258. "args": ["-y", "@circleci/mcp-server-circleci@latest"],
  259. "env": {
  260. "CIRCLECI_TOKEN": "your-circleci-token",
  261. "CIRCLECI_BASE_URL": "https://circleci.com",
  262. "MAX_MCP_OUTPUT_LENGTH": "50000"
  263. }
  264. }
  265. }
  266. }
  267. ```
  268. #### Using Docker in a local MCP Server
  269. Add the following to your Windsurf `mcp_config.json`:
  270. ```json
  271. {
  272. "mcpServers": {
  273. "circleci-mcp-server": {
  274. "command": "docker",
  275. "args": [
  276. "run",
  277. "--rm",
  278. "-i",
  279. "-e",
  280. "CIRCLECI_TOKEN",
  281. "-e",
  282. "CIRCLECI_BASE_URL",
  283. "-e",
  284. "MAX_MCP_OUTPUT_LENGTH",
  285. "circleci/mcp-server-circleci"
  286. ],
  287. "env": {
  288. "CIRCLECI_TOKEN": "your-circleci-token",
  289. "CIRCLECI_BASE_URL": "https://circleci.com",
  290. "MAX_MCP_OUTPUT_LENGTH": "50000"
  291. }
  292. }
  293. }
  294. }
  295. ```
  296. #### Using a Self-Managed Remote MCP Server
  297. See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use the [per-user client configuration](#client-configuration-per-user-tokens) in your Windsurf `mcp_config.json`.
  298. For more information: https://docs.windsurf.com/windsurf/mcp
  299. </details>
  300. <details>
  301. <summary><strong>Amazon Q Developer CLI</strong></summary>
  302. **Prerequisites:**
  303. - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/))
  304. - NPX: [Node.js](https://nodejs.org/) `^22.23.4 || ^24.22.1 || >=26.12.1` and [pnpm](https://pnpm.io/installation)
  305. MCP client configuration in Amazon Q Developer is stored in JSON format in a file named `mcp.json`. Two levels of configuration are supported:
  306. - **Global:** `~/.aws/amazonq/mcp.json` — applies to all workspaces
  307. - **Workspace:** `.amazonq/mcp.json` — specific to the current workspace
  308. If both files exist, their contents are merged. In case of conflict, the workspace config takes precedence.
  309. #### Using NPX in a local MCP Server
  310. Edit `~/.aws/amazonq/mcp.json` or create `.amazonq/mcp.json` with the following:
  311. ```json
  312. {
  313. "mcpServers": {
  314. "circleci-local": {
  315. "command": "npx",
  316. "args": [
  317. "-y",
  318. "@circleci/mcp-server-circleci@latest"
  319. ],
  320. "env": {
  321. "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
  322. "CIRCLECI_BASE_URL": "https://circleci.com",
  323. "MAX_MCP_OUTPUT_LENGTH": "50000"
  324. },
  325. "timeout": 60000
  326. }
  327. }
  328. }
  329. ```
  330. #### Using a Self-Managed Remote MCP Server
  331. See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use a wrapper script as shown in [Claude Desktop and CLI clients](#claude-desktop-and-cli-clients), then register it with `q mcp add`.
  332. </details>
  333. <details>
  334. <summary><strong>Amazon Q Developer in the IDE</strong></summary>
  335. **Prerequisites:**
  336. - [CircleCI Personal API token](https://app.circleci.com/settings/user/tokens) ([learn more](https://circleci.com/docs/managing-api-tokens/))
  337. - NPX: [Node.js](https://nodejs.org/) `^22.23.4 || ^24.22.1 || >=26.12.1` and [pnpm](https://pnpm.io/installation)
  338. #### Using NPX in a local MCP Server
  339. Edit `~/.aws/amazonq/mcp.json` or create `.amazonq/mcp.json` with the following:
  340. ```json
  341. {
  342. "mcpServers": {
  343. "circleci-local": {
  344. "command": "npx",
  345. "args": [
  346. "-y",
  347. "@circleci/mcp-server-circleci@latest"
  348. ],
  349. "env": {
  350. "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
  351. "CIRCLECI_BASE_URL": "https://circleci.com",
  352. "MAX_MCP_OUTPUT_LENGTH": "50000"
  353. },
  354. "timeout": 60000
  355. }
  356. }
  357. }
  358. ```
  359. #### Using a Self-Managed Remote MCP Server
  360. See [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server). Use a wrapper script as shown in [Claude Desktop and CLI clients](#claude-desktop-and-cli-clients), then add it via the MCP configuration UI:
  361. 1. [Access the MCP configuration UI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/mcp-ide.html#mcp-ide-configuration-access-ui)
  362. 2. Choose the **+** symbol
  363. 3. Select scope: **global** or **local**
  364. 4. Enter a name (e.g. `circleci-remote-mcp`)
  365. 5. Select transport protocol: **stdio**
  366. 6. Enter the command path to your script
  367. 7. Click **Save**
  368. </details>
  369. <details>
  370. <summary><strong>Smithery</strong></summary>
  371. To install CircleCI MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@CircleCI-Public/mcp-server-circleci):
  372. ```bash
  373. npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude
  374. ```
  375. </details>
  376. ## Self-Managed Remote MCP Server
  377. Run the MCP server centrally (for example on Kubernetes or Docker) so your team shares one deployment. Choose how developers authenticate:
  378. ### Choose a deployment mode
  379. | Mode | When to use | Server setup | Client setup | CircleCI audit trail |
  380. |------|-------------|--------------|--------------|----------------------|
  381. | **Per-user tokens** (recommended) | Teams with SSO-backed Personal API Tokens | `REQUIRE_REQUEST_TOKEN=true`, no server PAT | Each dev forwards their PAT | Per developer |
  382. | **Shared token** (interim) | Quick rollout, single service identity OK | `CIRCLECI_TOKEN` on server, `REQUIRE_REQUEST_TOKEN=false` (explicit opt-out) | No auth header needed | Single shared identity |
  383. > **Security:** Request authentication is **on by default** in remote mode. The shared-token mode disables it (`REQUIRE_REQUEST_TOKEN=false`), making every caller able to act as the server's `CIRCLECI_TOKEN` identity with no credentials — including triggering pipelines with arbitrary config. Only enable it on a network you fully trust, and prefer per-user tokens otherwise. Terminating TLS at an ingress provides encryption, not authentication.
  384. >
  385. > Because that combination is unsafe on a public interface, the server **refuses to start** when `REQUIRE_REQUEST_TOKEN=false` is combined with a non-loopback bind address, unless you explicitly accept the risk with `MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true`. The `Host`/`Origin` check is *not* a substitute for authentication — see [DNS-rebinding protection](#dns-rebinding-protection-is-not-authentication) below.
  386. ### 1. Deploy the server
  387. Both modes use remote HTTP mode (`start=remote`). Publish port `8000` (or your chosen port).
  388. **Per-user tokens (recommended) — accessed via `mcp-remote` from localhost:**
  389. ```bash
  390. docker run --rm -p 8000:8000 \
  391. -e start=remote \
  392. -e port=8000 \
  393. -e REQUIRE_REQUEST_TOKEN=true \
  394. circleci/mcp-server-circleci
  395. ```
  396. **Per-user tokens (recommended) — accessed via `mcp-remote` from a public hostname:**
  397. ```bash
  398. docker run --rm -p 8000:8000 \
  399. -e start=remote \
  400. -e port=8000 \
  401. -e REQUIRE_REQUEST_TOKEN=true \
  402. -e MCP_ALLOWED_HOSTS=my-mcp.example.com \
  403. circleci/mcp-server-circleci
  404. ```
  405. **Shared token (interim) — accessed via `mcp-remote` from a public hostname:**
  406. Because this mode serves the org's PAT to any caller with no credential, it must be
  407. run only where the published port is unreachable from untrusted networks, and you
  408. must acknowledge that explicitly or the server will refuse to start:
  409. ```bash
  410. docker run --rm -p 8000:8000 \
  411. -e start=remote \
  412. -e port=8000 \
  413. -e CIRCLECI_TOKEN=your-shared-circleci-pat \
  414. -e REQUIRE_REQUEST_TOKEN=false \
  415. -e MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true \
  416. -e MCP_ALLOWED_HOSTS=my-mcp.example.com \
  417. circleci/mcp-server-circleci
  418. ```
  419. Prefer putting authentication in front of the port instead — an ingress that
  420. requires SSO, mTLS, or an API key — or switch to per-user tokens above.
  421. **Environment variables:**
  422. | Variable | Description |
  423. |----------|-------------|
  424. | `start=remote` | Starts the HTTP+SSE MCP server instead of stdio |
  425. | `port` | Listening port inside the container (default: `8000`) |
  426. | `REQUIRE_REQUEST_TOKEN` | Reject requests without `Authorization: Bearer` or `Circle-Token` header. Defaults to required; set `REQUIRE_REQUEST_TOKEN=false` to allow unauthenticated requests (shared-token mode) |
  427. | `CIRCLECI_TOKEN` | Shared fallback PAT for all requests when per-user headers are not sent |
  428. | `CIRCLECI_BASE_URL` | Optional — required for on-prem only (default: `https://circleci.com`) |
  429. | `DISABLE_TELEMETRY=true` | Opt out of usage metrics export |
  430. | `MCP_ALLOWED_HOSTS` | Comma-separated list of additional `Host` header values to allow (e.g. `my-mcp.example.com,my-mcp.example.com:443`). Loopback hostnames are always allowed. Required for any non-loopback deployment. |
  431. | `MCP_ALLOWED_ORIGINS` | Comma-separated list of additional `Origin` header values to allow (e.g. `https://my-app.example.com`). Loopback origins are always allowed. Only needed when a browser directly reaches this server (not via `mcp-remote`). |
  432. | `MCP_BIND_HOST` | Network interface to bind to (default: `0.0.0.0`). Set to `127.0.0.1` to restrict to loopback only (not compatible with Docker `-p` port mapping). |
  433. | `MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS` | Required (`=true`) to start with `REQUIRE_REQUEST_TOKEN=false` on a non-loopback bind address. Acknowledges that any peer able to reach the port acts as the server's `CIRCLECI_TOKEN` identity without a credential. Has no effect when request tokens are required. |
  434. | `MCP_FILE_OUTPUT_ROOTS` | Comma-separated list of additional directories that file-reading/writing tools may use (e.g. `/srv/reports,/data/exports`). The working directory, home directory and temp directory are always allowed. See the note below. |
  435. > **File output locations (applies to both stdio and remote transports):** Tools that accept a filesystem path — `get_build_failure_logs` (`outputDir`), `download_usage_api_data` (`outputDir`) and `find_underused_resource_classes` (`csvFilePath`) — may only read and write inside the server's working directory, the user's home directory, and the system temp directory. Within those roots, hidden configuration directories (`~/.ssh`, `~/.aws`, `~/.config`, `.git`, …), `node_modules` and launch-agent directories are rejected, as are symlinks resolving outside the permitted roots. System directories (`/etc`, `/usr`, `/bin`, `/System`, `/Library`, `%SystemRoot%`, …) are refused unconditionally and cannot be re-enabled. Output files are never written through a symlink.
  436. >
  437. > If your checkout lives outside those roots — `/workspace` in a container, `/srv`, `/opt`, a secondary volume such as `/Volumes/work` — set `MCP_FILE_OUTPUT_ROOTS` to that directory, otherwise those paths are rejected. For a stdio server the working directory is usually already the project root, so no configuration is needed. This matters most for the remote transport, where the paths come from network clients rather than the local user.
  438. <a name="dns-rebinding-protection-is-not-authentication"></a>
  439. > **DNS-rebinding protection (not authentication):** The remote transport validates the `Host` header on every `/mcp` request. By default only loopback addresses (`localhost`, `127.0.0.1`, `[::1]`) are accepted. **Public deployments must set `MCP_ALLOWED_HOSTS`** to the hostname clients use, or all `/mcp` requests will receive `403 Forbidden`. The `/ping` health-check endpoint is not guarded so load-balancer probes continue to work regardless of `Host`.
  440. >
  441. > The `Origin` header (sent by browsers) is also validated when present. Non-browser clients such as `mcp-remote` never send `Origin`, so they are unaffected by this check.
  442. >
  443. > **This check is not an access control and must not be relied on as one.** Both headers are chosen by the caller, so any non-browser client — curl, a script, a raw socket — can send an allowed `Host` and omit `Origin` to satisfy it. Its only purpose is to stop a *browser* from being aimed at the server by attacker-controlled DNS, which is the DNS-rebinding threat. Authenticating callers is the job of `REQUIRE_REQUEST_TOKEN` (or an authenticating proxy in front of the port). Requiring an `Origin` header would break every legitimate CLI client while stopping no attacker.
  444. >
  445. > **Behind a reverse proxy:** If your proxy rewrites `Host` to the backend address (nginx's default), add `proxy_set_header Host $host;` to pass the original hostname through, then set `MCP_ALLOWED_HOSTS` to that public hostname. Alternatively, set `MCP_ALLOWED_HOSTS` to whatever hostname the proxy does forward.
  446. The server accepts per-request tokens via:
  447. - `Authorization: Bearer <circleci-pat>`
  448. - `Circle-Token: <circleci-pat>`
  449. If a client sends a header token, it takes precedence over `CIRCLECI_TOKEN` on the server.
  450. Telemetry metrics recorded during a request are exported using the same token as that request.
  451. ### 2. Configure clients
  452. Most MCP clients only support local (stdio) processes. Use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), a third-party stdio-to-HTTP bridge, to connect them to your remote server.
  453. > **URL scheme:** Use `http://localhost:8000/mcp` with `--allow-http` for local testing. In production, terminate TLS at your ingress/load balancer and use `https://your-host/mcp` without `--allow-http`.
  454. > **Windows:** Avoid spaces around the colon in `--header` values. Put the full `Bearer <token>` value in an environment variable.
  455. > **Security:** Examples use `npx` for convenience. For production or team rollouts, pin a specific version in your MCP config (for example `mcp-remote@0.1.38` instead of `mcp-remote`). Do not use versions below `0.1.16` ([CVE-2025-6514](https://www.npmjs.com/package/mcp-remote)).
  456. #### Client configuration: per-user tokens
  457. Each developer forwards their own CircleCI Personal API Token on every request:
  458. ```json
  459. {
  460. "inputs": [
  461. {
  462. "type": "promptString",
  463. "id": "circleci-token",
  464. "description": "CircleCI API Token",
  465. "password": true
  466. }
  467. ],
  468. "mcpServers": {
  469. "circleci-mcp-server-remote": {
  470. "command": "npx",
  471. "args": [
  472. "-y",
  473. "mcp-remote",
  474. "http://localhost:8000/mcp",
  475. "--allow-http",
  476. "--header",
  477. "Authorization:${AUTH_HEADER}"
  478. ],
  479. "env": {
  480. "AUTH_HEADER": "Bearer ${input:circleci-token}"
  481. }
  482. }
  483. }
  484. }
  485. ```
  486. Replace `http://localhost:8000/mcp` with your team's server URL. Cursor and VS Code support `${input:...}` prompts; other clients can set `AUTH_HEADER` directly.
  487. #### Client configuration: shared token
  488. When the server has `CIRCLECI_TOKEN` set and is started with `REQUIRE_REQUEST_TOKEN=false` (request auth is on by default and must be explicitly disabled, and a non-loopback bind additionally requires `MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true`), clients do not need to send a token:
  489. ```json
  490. {
  491. "mcpServers": {
  492. "circleci-mcp-server-remote": {
  493. "command": "npx",
  494. "args": [
  495. "-y",
  496. "mcp-remote",
  497. "http://localhost:8000/mcp",
  498. "--allow-http"
  499. ]
  500. }
  501. }
  502. }
  503. ```
  504. #### Claude Desktop and CLI clients
  505. Create a wrapper script (e.g. `circleci-remote-mcp.sh`):
  506. ```bash
  507. #!/bin/bash
  508. export AUTH_HEADER="Bearer your-circleci-token"
  509. npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}"
  510. ```
  511. Make it executable (`chmod +x circleci-remote-mcp.sh`), then reference it from your MCP config:
  512. ```json
  513. {
  514. "mcpServers": {
  515. "circleci-remote-mcp-server": {
  516. "command": "/full/path/to/circleci-remote-mcp.sh"
  517. }
  518. }
  519. }
  520. ```
  521. #### Claude Code
  522. ```bash
  523. claude mcp add circleci-mcp-server \
  524. -e AUTH_HEADER="Bearer your-circleci-token" \
  525. -- npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}"
  526. ```
  527. Omit `--header` and `AUTH_HEADER` when using a [shared-token server](#1-deploy-the-server).
  528. ### 3. Verify the deployment
  529. ```bash
  530. # Health check (no auth required)
  531. curl http://localhost:8000/ping
  532. # Should return 401 when REQUIRE_REQUEST_TOKEN=true and no token is sent
  533. curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \
  534. -H "Content-Type: application/json" \
  535. -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
  536. # Should return 200 with a valid Bearer token and MCP Accept headers
  537. curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \
  538. -H "Content-Type: application/json" \
  539. -H "Accept: application/json, text/event-stream" \
  540. -H "Authorization: Bearer your-circleci-pat" \
  541. -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
  542. ```
  543. ## Demo
  544. <details>
  545. <summary><strong>Watch it in action</strong></summary>
  546. Example: "Find the latest failed pipeline on my branch and get logs"
  547. — see the [wiki](https://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide) for more examples.
  548. https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74
  549. </details>
  550. ## Tool Details
  551. <details>
  552. <summary id="config_helper"><strong><code>config_helper</code></strong></summary>
  553. Assists with CircleCI configuration tasks by providing guidance and validation.
  554. - Validates your `.circleci/config.yml` for syntax and semantic errors
  555. - Provides detailed validation results and configuration recommendations
  556. - Example: "Validate my CircleCI config"
  557. </details>
  558. <details>
  559. <summary id="download_usage_api_data"><strong><code>download_usage_api_data</code></strong></summary>
  560. Downloads usage data from the CircleCI Usage API for a given organization. Accepts flexible date input (e.g., "March 2025" or "last month"). Cloud-only feature.
  561. **Option 1:** Start a new export job by providing:
  562. - `orgId`, `startDate`, `endDate` (max 32 days), `outputDir`
  563. **Option 2:** Check/download an existing export job by providing:
  564. - `orgId`, `jobId`, `outputDir`
  565. Returns a CSV file with CircleCI usage data for the specified time frame.
  566. > [!NOTE]
  567. > Usage data can be fed into the `find_underused_resource_classes` tool for cost optimization analysis.
  568. </details>
  569. <details>
  570. <summary id="find_flaky_tests"><strong><code>find_flaky_tests</code></strong></summary>
  571. Identifies flaky tests in your CircleCI project by analyzing test execution history. Leverages the [flaky test detection feature](https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detection) in CircleCI.
  572. This tool can be used in three ways:
  573. 1. **Using Project Slug (Recommended):**
  574. - First use `list_followed_projects` to get your projects, then:
  575. - Example: "Get flaky tests for my-project"
  576. 2. **Using CircleCI Project URL:**
  577. - Example: "Find flaky tests in https://app.circleci.com/pipelines/github/org/repo"
  578. 3. **Using Local Project Context:**
  579. - Works from your local workspace by providing workspace root and git remote URL
  580. - Example: "Find flaky tests in my current project"
  581. Output modes:
  582. - **Text (default):** Returns flaky test details in text format
  583. - **File** (requires `FILE_OUTPUT_DIRECTORY` env var): Creates a directory with flaky test details
  584. </details>
  585. <details>
  586. <summary id="find_underused_resource_classes"><strong><code>find_underused_resource_classes</code></strong></summary>
  587. Analyzes a CircleCI usage data CSV file to find jobs with average or max CPU/RAM usage below a given threshold (default: 40%).
  588. Provide a CSV file obtained from `download_usage_api_data`.
  589. Returns a markdown list of underused jobs organized by project and workflow — useful for identifying cost optimization opportunities.
  590. </details>
  591. <details>
  592. <summary id="get_build_failure_logs"><strong><code>get_build_failure_logs</code></strong></summary>
  593. Retrieves detailed failure logs from CircleCI builds. This tool can be used in three ways:
  594. 1. **Using Project Slug and Branch (Recommended):**
  595. - First use `list_followed_projects` to get your projects, then:
  596. - Example: "Get build failures for my-project on the main branch"
  597. 2. **Using CircleCI URLs:**
  598. - Provide a failed job URL or pipeline URL directly
  599. - Example: "Get logs from https://app.circleci.com/pipelines/github/org/repo/123"
  600. 3. **Using Local Project Context:**
  601. - Works from your local workspace by providing workspace root, git remote URL, and branch name
  602. - Example: "Find the latest failed pipeline on my current branch"
  603. The tool returns formatted logs including:
  604. - Job names
  605. - Step-by-step execution details
  606. - Failure messages and context
  607. </details>
  608. <details>
  609. <summary id="get_job_test_results"><strong><code>get_job_test_results</code></strong></summary>
  610. Retrieves test metadata for CircleCI jobs, allowing you to analyze test results without leaving your IDE. This tool can be used in three ways:
  611. 1. **Using Project Slug and Branch (Recommended):**
  612. - Example: "Get test results for my-project on the main branch"
  613. 2. **Using CircleCI URL:**
  614. - Job URL: `https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789`
  615. - Workflow URL: `https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def`
  616. - Pipeline URL: `https://app.circleci.com/pipelines/github/org/repo/123`
  617. 3. **Using Local Project Context:**
  618. - Works from your local workspace by providing workspace root, git remote URL, and branch name
  619. The tool returns:
  620. - Summary of all tests (total, successful, failed)
  621. - Detailed info on failed tests: name, class, file, error message, duration
  622. - List of successful tests with timing
  623. - Filter by test result
  624. > [!NOTE]
  625. > Test metadata must be configured in your CircleCI config. See [Collect Test Data](https://circleci.com/docs/collect-test-data/) for setup instructions.
  626. </details>
  627. <details>
  628. <summary id="get_latest_pipeline_status"><strong><code>get_latest_pipeline_status</code></strong></summary>
  629. Retrieves the status of the latest pipeline for a given branch. This tool can be used in three ways:
  630. 1. **Using Project Slug and Branch (Recommended):**
  631. - Example: "Get the status of the latest pipeline for my-project on the main branch"
  632. 2. **Using CircleCI Project URL:**
  633. - Example: "Get the status of the latest pipeline for https://app.circleci.com/pipelines/github/org/repo"
  634. 3. **Using Local Project Context:**
  635. - Works from your local workspace by providing workspace root, git remote URL, and branch name
  636. Example output:
  637. ```
  638. ---
  639. Workflow: build
  640. Status: success
  641. Duration: 5 minutes
  642. Created: 4/20/2025, 10:15:30 AM
  643. Stopped: 4/20/2025, 10:20:45 AM
  644. ---
  645. Workflow: test
  646. Status: running
  647. Duration: unknown
  648. Created: 4/20/2025, 10:21:00 AM
  649. Stopped: in progress
  650. ```
  651. </details>
  652. <details>
  653. <summary id="list_artifacts"><strong><code>list_artifacts</code></strong></summary>
  654. Retrieves the list of artifacts produced by a CircleCI job. This tool can be used in three ways:
  655. 1. **Using Project Slug and Branch (Recommended):**
  656. - First use `list_followed_projects` to get your projects, then:
  657. - Example: "List artifacts for my-project on the main branch"
  658. 2. **Using CircleCI URL:**
  659. - Job URL: `https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789`
  660. - Workflow URL: `https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def`
  661. - Pipeline URL: `https://app.circleci.com/pipelines/gh/organization/project/123`
  662. 3. **Using Local Project Context:**
  663. - Works from your local workspace by providing workspace root, git remote URL, and branch name
  664. Useful for:
  665. - Finding download URLs for build artifacts (binaries, reports, logs)
  666. - Checking what artifacts were produced by a pipeline run
  667. </details>
  668. <details>
  669. <summary id="list_component_versions"><strong><code>list_component_versions</code></strong></summary>
  670. Lists all versions for a specific CircleCI component in an environment. Includes deployment status, commit information, and timestamps.
  671. The tool will prompt you to select the component and environment if not provided.
  672. Useful for:
  673. - Identifying which version is currently live
  674. - Selecting target versions for rollback operations
  675. - Getting deployment details (pipeline, workflow, job)
  676. </details>
  677. <details>
  678. <summary id="list_followed_projects"><strong><code>list_followed_projects</code></strong></summary>
  679. Lists all projects that the user is following on CircleCI.
  680. - Shows all projects you have access to with their `projectSlug`
  681. - Example: "List my CircleCI projects"
  682. Example output:
  683. ```
  684. Projects followed:
  685. 1. my-project (projectSlug: gh/organization/my-project)
  686. 2. another-project (projectSlug: gh/organization/another-project)
  687. ```
  688. > [!NOTE]
  689. > The `projectSlug` (not the project name) is required for many other CircleCI tools.
  690. </details>
  691. <details>
  692. <summary id="rerun_workflow"><strong><code>rerun_workflow</code></strong></summary>
  693. Reruns a workflow from its start or from the failed job.
  694. Returns the ID of the newly-created workflow and a link to monitor it.
  695. </details>
  696. <details>
  697. <summary id="run_pipeline"><strong><code>run_pipeline</code></strong></summary>
  698. Triggers a pipeline to run. This tool can be used in three ways:
  699. 1. **Using Project Slug and Branch (Recommended):**
  700. - Example: "Run the pipeline for my-project on the main branch"
  701. 2. **Using CircleCI URL:**
  702. - Pipeline URL, Workflow URL, Job URL, or Project URL with branch
  703. - Example: "Run the pipeline for https://app.circleci.com/pipelines/github/org/repo/123"
  704. 3. **Using Local Project Context:**
  705. - Works from your local workspace by providing workspace root, git remote URL, and branch name
  706. The tool returns a link to monitor the pipeline execution.
  707. </details>
  708. <details>
  709. <summary id="run_rollback_pipeline"><strong><code>run_rollback_pipeline</code></strong></summary>
  710. Triggers a rollback for a CircleCI project. The tool interactively guides you through:
  711. 1. **Project Selection** — lists followed projects for you to choose from
  712. 2. **Environment Selection** — lists available environments (auto-selects if only one)
  713. 3. **Component Selection** — lists available components (auto-selects if only one)
  714. 4. **Version Selection** — displays available versions; you select the target for rollback
  715. 5. **Rollback Mode Detection** — checks if a rollback pipeline is configured
  716. 6. **Execute Rollback** — two options:
  717. - **Pipeline Rollback:** triggers the rollback pipeline
  718. - **Workflow Rerun:** reruns a previous workflow using its workflow ID
  719. 7. **Confirmation** — summarizes and confirms before execution
  720. </details>
  721. ## Troubleshooting
  722. <details>
  723. <summary><strong>Quick Fixes</strong></summary>
  724. **Most common issues:**
  725. 1. **Clear package caches:**
  726. ```bash
  727. npx clear-npx-cache
  728. npm cache clean --force
  729. ```
  730. 2. **Force latest version:** Add `@latest` to your config:
  731. ```json
  732. "args": ["-y", "@circleci/mcp-server-circleci@latest"]
  733. ```
  734. 3. **Restart your IDE completely** (not just reload window)
  735. </details>
  736. <details>
  737. <summary><strong>Authentication Issues</strong></summary>
  738. - **Invalid token errors:** Verify your `CIRCLECI_TOKEN` in [Personal API Tokens](https://app.circleci.com/settings/user/tokens)
  739. - **Permission errors:** Ensure the token has read access to your projects
  740. - **Environment variables not loading:** Test with `echo $CIRCLECI_TOKEN` (Mac/Linux) or `echo %CIRCLECI_TOKEN%` (Windows)
  741. </details>
  742. <details>
  743. <summary><strong>Connection and Network Issues</strong></summary>
  744. - **Base URL:** Confirm `CIRCLECI_BASE_URL` is `https://circleci.com`
  745. - **Corporate networks:** Configure npm proxy settings if behind a firewall
  746. - **Firewall blocking:** Check if security software blocks package downloads
  747. </details>
  748. <details>
  749. <summary><strong>System Requirements</strong></summary>
  750. - **Node.js version:** Ensure it satisfies `^22.23.4 || ^24.22.1 || >=26.12.1` with `node --version`
  751. - **Update Node.js:** Consider latest LTS if experiencing compatibility issues
  752. - **Package manager:** Verify npm/pnpm is working: `npm --version`
  753. </details>
  754. <details>
  755. <summary><strong>IDE-Specific Issues</strong></summary>
  756. - **Config file location:** Double-check the path for your OS
  757. - **Syntax errors:** Validate JSON syntax in your config file
  758. - **Console logs:** Check the IDE developer console for specific errors
  759. - **Try a different IDE:** Test in another supported editor to isolate the issue
  760. </details>
  761. <details>
  762. <summary><strong>Process Issues</strong></summary>
  763. **Hanging processes — kill existing MCP processes:**
  764. ```bash
  765. # Mac/Linux:
  766. pkill -f "mcp-server-circleci"
  767. # Windows:
  768. taskkill /f /im node.exe
  769. ```
  770. **Port conflicts:** Restart your IDE if the connection seems blocked.
  771. </details>
  772. <details>
  773. <summary><strong>Advanced Debugging</strong></summary>
  774. - **Test package directly:** `npx @circleci/mcp-server-circleci@latest --help`
  775. - **Verbose logging:** `DEBUG=* npx @circleci/mcp-server-circleci@latest`
  776. - **Docker fallback:** Try Docker installation if npx fails consistently
  777. **Still need help?**
  778. 1. Check [GitHub Issues](https://github.com/CircleCI-Public/mcp-server-circleci/issues) for similar problems
  779. 2. Include your OS, Node version, and IDE when reporting issues
  780. 3. Share relevant error messages from the IDE console
  781. </details>
  782. ## Telemetry
  783. The server supports OpenTelemetry metrics for tracking tool usage. Metrics are exported unless you set `DISABLE_TELEMETRY=true`. On remote deployments, metrics use the same token as the request (per-user PAT or shared server PAT).
  784. | Metric | Description |
  785. |--------|-------------|
  786. | `circleci.mcp.tool.invocations` | Tool invocation count |
  787. | `circleci.mcp.tool.duration_ms` | Execution time in ms |
  788. | `circleci.mcp.tool.errors` | Error count |
  789. # Development
  790. ## Getting Started
  791. 1. Clone the repository:
  792. ```bash
  793. git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
  794. cd mcp-server-circleci
  795. ```
  796. 2. Install dependencies:
  797. ```bash
  798. pnpm install
  799. ```
  800. 3. Build the project:
  801. ```bash
  802. pnpm build
  803. ```
  804. ## Building Docker Container
  805. You can build the Docker container locally using:
  806. ```bash
  807. docker build -t circleci:mcp-server-circleci .
  808. ```
  809. This will create a Docker image tagged as `circleci:mcp-server-circleci` that you can use with any MCP client.
  810. **Local stdio mode** (single developer, token on the client):
  811. ```bash
  812. docker run --rm -i \
  813. -e CIRCLECI_TOKEN=your-circleci-token \
  814. -e CIRCLECI_BASE_URL=https://circleci.com \
  815. circleci/mcp-server-circleci
  816. ```
  817. **Remote mode** (centralized server for a team): see [Self-Managed Remote MCP Server](#self-managed-remote-mcp-server).
  818. ## Development with MCP Inspector
  819. The 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
  820. 1. Start the development server:
  821. ```bash
  822. pnpm watch # Keep this running in one terminal
  823. ```
  824. 2. In a separate terminal, launch the inspector:
  825. ```bash
  826. pnpm inspector
  827. ```
  828. 3. Configure the environment:
  829. - Add your `CIRCLECI_TOKEN` to the Environment Variables section in the inspector UI
  830. - The token needs read access to your CircleCI projects
  831. - Optionally set your CircleCI Base URL (defaults to `https://circleci.com`)
  832. ## Testing
  833. - Run the test suite:
  834. ```bash
  835. pnpm test
  836. ```
  837. - Run tests in watch mode during development:
  838. ```bash
  839. pnpm test:watch
  840. ```
  841. For more detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.