mcp -circleci

This MCP server exposes CircleCI tooling via the Model Context Protocol, allowing LLMs and other MCP clients to interact with CircleCI resources using natural language prompts. The server provides capabilities such as retrieving build failure logs, inspecting test results, triggering pipelines, and more through a collection of tools (e.g., get_build_failure_logs, run_pipeline, get_latest_pipeline_status). To use it, configure an MCP client (Cursor, Windsurf, Copilot, Claude, or any MCP-compatible client) to point at either the NPX-based instance or the Docker-based instance, supply the CircleCI API token and any required base URL, and then start the server. Once running, you can query CircleCI data, validate configuration templates, generate prompts, and automate workflows via natural language interactions with Discord, IDEs, or your preferred environment.

Prerequisites:

• Node.js v18+ with npm/npx or Docker, depending on chosen deployment
• CircleCI API token with appropriate permissions

Option A: Run with NPX (local development)

1. Ensure Node.js is installed.
2. In your MCP client config, add:

{
  "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"
      }
    }
  }
}

3. Start your MCP client and connect to the server configuration.

Option B: Run with Docker

1. Ensure Docker is installed and running.
2. In your MCP client config, add:

{
  "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"
      }
    }
  }
}

3. Start your MCP client and connect to the server configuration.

Environment variables: CIRCLECI_TOKEN should be a valid CircleCI API token. CIRCLECI_BASE_URL is optional and needed for on-prem deployments. MAX_MCP_OUTPUT_LENGTH controls the maximum length of MCP outputs (default ~50k). If you encounter authentication errors, re-check token scopes and ensure the token is active. For Docker deployments, ensure the image circleci/mcp-server-circleci is pulled or accessible. You can use either NPX or Docker depending on your environment preferences; both expose the same MCP capabilities.