Circleci Mcpサーバー

mcp-server-circleciとは？

mcp-server-circleciは、モデルコンテキストプロトコル（MCP）用に設計された専門的なサーバー実装であり、CircleCIの開発ワークフローとシームレスに統合されます。このプロジェクトは、CircleCIのインフラストラクチャとモデルコンテキストプロトコルの間の橋渡しを行い、AI駆動の機能で開発体験を向上させます。これにより、開発者はCircleCIの力を活用しながら、MCPの高度な機能を利用することができます。

mcp-server-circleciの特徴

• CircleCIとの統合：サーバーはCircleCIエコシステム内で動作するように特別に構築されており、CI/CDプロセスを強化するスムーズな統合を提供します。
• AI駆動の開発：モデルコンテキストプロトコルを利用することで、開発者はワークフローを効率化し、生産性を向上させるAI駆動の機能を享受できます。
• オープンソース：プロジェクトは公開されており、開発者はニーズに応じてサーバーを貢献、変更、強化することができます。
• 包括的なドキュメント：ユーザーがサーバーを効果的に実装し利用するための包括的なドキュメントが提供されています。
• コミュニティサポート：CircleCIの公開組織の一部であるため、ユーザーはトラブルシューティングやベストプラクティスのためのコミュニティサポートとリソースにアクセスできます。

mcp-server-circleciの使い方

1. インストール：まず、GitHubからリポジトリをクローンします：

   git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
   

2. 設定：ドキュメントのセットアップ手順に従って、プロジェクトの要件に応じてサーバーを設定します。
3. 統合：ドキュメントに記載されたガイドラインに従って、CircleCIプロジェクトにサーバーを統合します。
4. 利用：AI機能と改善されたCI/CDプロセスを活用して、開発ワークフローを強化するためにサーバーを使用し始めます。

よくある質問

モデルコンテキストプロトコル（MCP）とは？

モデルコンテキストプロトコル（MCP）は、特にAIや機械学習の文脈で、異なるシステム間の通信とデータ交換を促進するために設計されたプロトコルです。これにより、さまざまなプラットフォーム間での相互運用性と機能性が向上します。

mcp-server-circleciは無料で使用できますか？

はい、mcp-server-circleciはApache-2.0ライセンスの下でリリースされたオープンソースプロジェクトであり、無料で使用、変更、配布することができます。

mcp-server-circleciプロジェクトにどのように貢献できますか？

リポジトリをフォークし、変更を加えてプルリクエストを提出することで貢献できます。また、プロジェクトのGitHubページを通じて問題を報告したり、機能を提案したりすることもできます。

mcp-server-circleciのドキュメントはどこで見つけられますか？

ドキュメントはリポジトリ内にあり、さらに詳細情報については公式のCircleCI MCPページ（circleci.com/mcp）を訪れることもできます。

CircleCI MCP Server

Model Context Protocol (MCP) is a new, standardized protocol for managing context between large language models (LLMs) and external systems. In this repository, we provide an MCP Server for CircleCI.

This lets you use Cursor IDE, Windsurf, Copilot, or any MCP supported Client, to use natural language to accomplish things with CircleCI, e.g.:

• Find the latest failed pipeline on my branch and get logs https://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide

https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74

Requirements

• CircleCI Personal API Token - you can generate one through the CircleCI. Learn more or click here for quick access.

For NPX installation:

• pnpm package manager - Learn more
• Node.js >= v18.0.0

For Docker installation:

• Docker - Learn more

Installation

Cursor

Using NPX

Add the following to your cursor MCP config:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      }
    }
  }
}

Using Docker

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",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      }
    }
  }
}

VS Code

Using NPX

To install CircleCI MCP Server for VS Code in .vscode/mcp.json:

{
  // 💡 Inputs are prompted on first server start, then stored securely by VS Code.
  "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": {
    // https://github.com/ppl-ai/modelcontextprotocol/
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

Using Docker

To install CircleCI MCP Server for VS Code in .vscode/mcp.json using Docker:

{
  // 💡 Inputs are prompted on first server start, then stored securely by VS Code.
  "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": {
    // https://github.com/ppl-ai/modelcontextprotocol/
    "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}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

Claude Desktop

Using NPX

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      }
    }
  }
}

To locate this file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop setup

Using Docker

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      }
    }
  }
}

To 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"

This will create a configuration file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

See the guide below for more information on using MCP servers with Claude Desktop: https://modelcontextprotocol.io/quickstart/user

Claude Code

Using NPX

After installing Claude Code, run the following command:

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci

Using Docker

After installing Claude Code, run the following command:

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

See the guide below for more information on using MCP servers with Claude Code: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp

Windsurf

Using NPX

Add the following to your windsurf mcp_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      }
    }
  }
}

Using Docker

Add the following to your windsurf mcp_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci:mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
      }
    }
  }
}

See the guide below for more information on using MCP servers with windsurf: https://docs.windsurf.com/windsurf/mcp

Installing via Smithery

To install CircleCI MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude

Features

Supported Tools

• get_build_failure_logs

  Retrieves detailed failure logs from CircleCI builds. This tool can be used in three ways:

  1. Using Project Slug and Branch (Recommended Workflow):

     • First, list your available projects:
       • Use the list_followed_projects tool to get your projects
       • Example: "List my CircleCI projects"
       • Then choose the project, which has a projectSlug associated with it
       • Example: "Lets use my-project"
     • Then ask to retrieve the build failure logs for a specific branch:
       • Example: "Get build failures for my-project on the main branch"

  2. Using CircleCI URLs:

     • Provide a failed job URL or pipeline URL directly
     • Example: "Get logs from https://app.circleci.com/pipelines/github/org/repo/123"

  3. Using Local Project Context:

     • Works from your local workspace by providing:
       • Workspace root path
       • Git remote URL
       • Branch name
     • Example: "Find the latest failed pipeline on my current branch"

  The tool returns formatted logs including:

  • Job names
  • Step-by-step execution details
  • Failure messages and context

  This is particularly useful for:

  • Debugging failed builds
  • Analyzing test failures
  • Investigating deployment issues
  • Quick access to build logs without leaving your IDE

• find_flaky_tests

  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

  This tool can be used in three ways:

  1. Using Project Slug (Recommended Workflow):

     • First, list your available projects:
       • Use the list_followed_projects tool to get your projects
       • Example: "List my CircleCI projects"
       • Then choose the project, which has a projectSlug associated with it
       • Example: "Lets use my-project"
     • Then ask to retrieve the flaky tests:
       • Example: "Get flaky tests for my-project"

  2. Using CircleCI Project URL:

     • Provide the project URL directly from CircleCI
     • Example: "Find flaky tests in https://app.circleci.com/pipelines/github/org/repo"

  3. Using Local Project Context:

     • Works from your local workspace by providing:
       • Workspace root path
       • Git remote URL
     • Example: "Find flaky tests in my current project"

  The tool can be used in two ways:

  1. Using text output mode (default):
     • This will return the flaky tests and their details in a text format
  2. Using file output mode: (requires the FILE_OUTPUT_DIRECTORY environment variable to be set)
     • This will create a directory with the flaky tests and their details

  The tool returns detailed information about flaky tests, including:

  • Test names and file locations
  • Failure messages and contexts

  This helps you:

  • Identify unreliable tests in your test suite
  • Get detailed context about test failures
  • Make data-driven decisions about test improvements

• get_latest_pipeline_status

  Retrieves the status of the latest pipeline for a given branch. This tool can be used in three ways:

  1. Using Project Slug and Branch (Recommended Workflow):

     • First, list your available projects:
       • Use the list_followed_projects tool to get your projects
       • Example: "List my CircleCI projects"
       • Then choose the project, which has a projectSlug associated with it
       • Example: "Lets use my-project"
     • Then ask to retrieve the latest pipeline status for a specific branch:
       • Example: "Get the status of the latest pipeline for my-project on the main branch"

  2. Using CircleCI Project URL:

     • Provide the project URL directly from CircleCI
     • Example: "Get the status of the latest pipeline for https://app.circleci.com/pipelines/github/org/repo"

  3. Using Local Project Context:

     • Works from your local workspace by providing:
       • Workspace root path
       • Git remote URL
       • Branch name
     • Example: "Get the status of the latest pipeline for my current project"

  The tool returns a formatted status of the latest pipeline:

  • Workflow names and their current status
  • Duration of each workflow
  • Creation and completion timestamps
  • Overall pipeline health

  Example output:

  
  Workflow: build
  Status: success
  Duration: 5 minutes
  Created: 4/20/2025, 10:15:30 AM
  Stopped: 4/20/2025, 10:20:45 AM
  
  Workflow: test
  Status: running
  Duration: unknown
  Created: 4/20/2025, 10:21:00 AM
  Stopped: in progress
  

  This is particularly useful for:

  • Checking the status of the latest pipeline
  • Getting the status of the latest pipeline for a specific branch
  • Quickly checking the status of the latest pipeline without leaving your IDE

• get_job_test_results

  Retrieves test metadata for CircleCI jobs, allowing you to analyze test results without leaving your IDE. This tool can be used in three ways:

  1. Using Project Slug and Branch (Recommended Workflow):

     • First, list your available projects:
       • Use the list_followed_projects tool to get your projects
       • Example: "List my CircleCI projects"
       • Then choose the project, which has a projectSlug associated with it
       • Example: "Lets use my-project"
     • Then ask to retrieve the test results for a specific branch:
       • Example: "Get test results for my-project on the main branch"

  2. Using CircleCI URL:

     • Provide a CircleCI URL in any of these formats:
       • Job URL: "https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789"
       • Workflow URL: "https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def"
       • Pipeline URL: "https://app.circleci.com/pipelines/github/org/repo/123"
     • Example: "Get test results for https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def"

  3. Using Local Project Context:

     • Works from your local workspace by providing:
       • Workspace root path
       • Git remote URL
       • Branch name
     • Example: "Get test results for my current project on the main branch"

  The tool returns detailed test result information:

  • Summary of all tests (total, successful, failed)
  • Detailed information about failed tests including:
    • Test name and class
    • File location
    • Error messages
    • Runtime duration
  • List of successful tests with timing information
  • Filter by tests result

  This is particularly useful for:

  • Quickly analyzing test failures without visiting the CircleCI web UI
  • Identifying patterns in test failures
  • Finding slow tests that might need optimization
  • Checking test coverage across your project
  • Troubleshooting flaky tests

  Note: The tool requires that test metadata is properly configured in your CircleCI config. For more information on setting up test metadata collection, see: https://circleci.com/docs/collect-test-data/

• config_helper

  Assists with CircleCI configuration tasks by providing guidance and validation. This tool helps you:

  1. Validate CircleCI Config:
     • Checks your .circleci/config.yml for syntax and semantic errors
     • Example: "Validate my CircleCI config"

  The tool provides:

  • Detailed validation results
  • Configuration recommendations

  This helps you:

  • Catch configuration errors before pushing
  • Learn CircleCI configuration best practices
  • Troubleshoot configuration issues
  • Implement CircleCI features correctly

• create_prompt_template

  Helps generate structured prompt templates for AI-enabled applications based on feature requirements. This tool:

  1. Converts Feature Requirements to Structured Prompts:
     • Transforms user requirements into optimized prompt templates
     • Example: "Create a prompt template for generating bedtime stories by age and topic"

  The tool provides:

  • A structured prompt template
  • A context schema defining required input parameters

  This helps you:

  • Create effective prompts for AI applications
  • Standardize input parameters for consistent results
  • Build robust AI-powered features

• recommend_prompt_template_tests

  Generates test cases for prompt templates to ensure they produce expected results. This tool:

  1. Provides Test Cases for Prompt Templates:
     • Creates diverse test scenarios based on your prompt template and context schema
     • Example: "Generate tests for my bedtime story prompt template"

  The tool provides:

  • An array of recommended test cases
  • Various parameter combinations to test template robustness

  This helps you:

  • Validate prompt template functionality
  • Ensure consistent AI responses across inputs
  • Identify edge cases and potential issues
  • Improve overall AI application quality

• list_followed_projects

  Lists all projects that the user is following on CircleCI. This tool:

  1. Retrieves and Displays Projects:
     • Shows all projects the user has access to and is following
     • Provides the project name and projectSlug for each entry
     • Example: "List my CircleCI projects"

  The tool returns a formatted list of projects, example output:

  Projects followed:
  1. my-project (projectSlug: gh/organization/my-project)
  2. another-project (projectSlug: gh/organization/another-project)
  

  This is particularly useful for:

  • Identifying which CircleCI projects are available to you
  • Obtaining the projectSlug needed for other CircleCI tools
  • Selecting a project for subsequent operations

  Note: The projectSlug (not the project name) is required for many other CircleCI tools, and will be used for those tool calls after a project is selected.

• run_pipeline

  Triggers a pipeline to run. This tool can be used in three ways:

  1. Using Project Slug and Branch (Recommended Workflow):

     • First, list your available projects:
       • Use the list_followed_projects tool to get your projects
       • Example: "List my CircleCI projects"
       • Then choose the project, which has a projectSlug associated with it
       • Example: "Lets use my-project"
     • Then ask to run the pipeline for a specific branch:
       • Example: "Run the pipeline for my-project on the main branch"

  2. Using CircleCI URL:

     • Provide a CircleCI URL in any of these formats:
       • Job URL: "https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789"
       • Workflow URL: "https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def"
       • Pipeline URL: "https://app.circleci.com/pipelines/github/org/repo/123"
       • Project URL with branch: "https://app.circleci.com/projects/github/org/repo?branch=main"
     • Example: "Run the pipeline for https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def"

  3. Using Local Project Context:

     • Works from your local workspace by providing:
       • Workspace root path
       • Git remote URL
       • Branch name
     • Example: "Run the pipeline for my current project on the main branch"

  The tool returns a link to monitor the pipeline execution.

  This is particularly useful for:

  • Quickly running pipelines without visiting the CircleCI web UI
  • Running pipelines from a specific branch

• rerun_workflow

  Reruns a workflow from its start or from the failed job.

  The tool returns the ID of the newly-created workflow, and a link to monitor the new workflow.

  This is particularly useful for:

  • Quickly rerunning a workflow from its start or from the failed job without visiting the CircleCI web UI

• analyze_diff

  Analyzes git diffs against cursor rules to identify rule violations.

  This tool can be used by providing:

  1. Git Diff Content:

     • Staged changes: git diff --cached
     • Unstaged changes: git diff
     • All changes: git diff HEAD
     • Example: "Analyze my staged changes against the cursor rules"

  2. Repository Rules:

     • Rules from .cursorrules file in your repository root
     • Rules from .cursor/rules directory
     • Multiple rule files combined with `` separator
     • Example: "Check my diff against the TypeScript coding standards"

  The tool provides:

  • Detailed violation reports with confidence scores
  • Specific explanations for each rule violation

  Example usage scenarios:

  • "Analyze my staged changes for any rule violations"
  • "Check my unstaged changes against rules"

  This is particularly useful for:

  • Pre-commit code quality checks
  • Ensuring consistency with team coding standards
  • Catching rule violations before code review

  The tool integrates with your existing cursor rules setup and provides immediate feedback on code quality, helping you catch issues early in the development process.

Development

Getting Started

1. Clone the repository:

   git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
   cd mcp-server-circleci
   

2. Install dependencies:

   pnpm install
   

3. Build the project:

   pnpm build
   

Building Docker Container

You can build the Docker container locally using:

docker build -t circleci:mcp-server-circleci .

This will create a Docker image tagged as circleci:mcp-server-circleci that you can use with any MCP client.

To run the container:

docker run --rm -i -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com circleci:mcp-server-circleci

Development with MCP Inspector

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

1. Start the development server:

   pnpm watch # Keep this running in one terminal
   

2. In a separate terminal, launch the inspector:

   pnpm inspector
   

3. Configure the environment:

   • Add your CIRCLECI_TOKEN to the Environment Variables section in the inspector UI
   • The token needs read access to your CircleCI projects
   • Optionally you can set your CircleCI Base URL. Defaults to https//circleci.com

Testing

• Run the test suite:

  pnpm test
  

• Run tests in watch mode during development:

  pnpm test:watch
  

For more detailed contribution guidelines, see CONTRIBUTING.md