CircleCI MCP サーバー

モデルコンテキストプロトコル（MCP）は、大規模言語モデル（LLM）と外部システム間のコンテキストを管理するための新しい標準化プロトコルです。このリポジトリでは、 CircleCI用のMCPサーバーを提供します。

これにより、Cursor IDE、Windsurf、Copilot、または MCP でサポートされている任意のクライアントを使用して、自然言語で CircleCI で次の操作を実行できるようになります。

• Find the latest failed pipeline on my branch and get logshttps://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

要件

• CircleCI APIトークン - CircleCIから生成できます。詳細はこちらをご覧ください。または、こちらをクリックしてクイックアクセスしてください。

NPX インストールの場合:

• pnpm パッケージマネージャー -詳細はこちら

• Node.js >= v18.0.0

Docker インストールの場合:

• Docker -詳細はこちら

インストール

カーソル

NPXの使用

カーソル MCP 構成に以下を追加します。

Dockerの使用

カーソル MCP 構成に以下を追加します。

VSコード

NPXの使用

.vscode/mcp.jsonに VS Code 用の CircleCI MCP Server をインストールするには:

Dockerの使用

Docker を使用して.vscode/mcp.jsonに VS Code 用の CircleCI MCP Server をインストールするには:

クロードデスクトップ

NPXの使用

claude_desktop_config.json に次の内容を追加します。

Dockerの使用

claude_desktop_config.json に次の内容を追加します。

このファイルを見つける/作成するには、まずClaudeデスクトップの設定を開きます。次に、設定パネルの左側のバーにある「開発」をクリックし、「設定の編集」をクリックします。

これにより、次の場所に構成ファイルが作成されます。

• macOS: ~/ライブラリ/アプリケーションサポート/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop で MCP サーバーを使用する方法の詳細については、以下のガイドを参照してください: https://modelcontextprotocol.io/quickstart/user

クロード・コード

NPXの使用

Claude Code をインストールした後、次のコマンドを実行します。

Dockerの使用

Claude Code をインストールした後、次のコマンドを実行します。

Claude Code で MCP サーバーを使用する方法の詳細については、以下のガイドを参照してください: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp

ウィンドサーフィン

NPXの使用

windsurf mcp_config.json に以下を追加します。

Dockerの使用

windsurf mcp_config.json に以下を追加します。

Windsurf で MCP サーバーを使用する方法の詳細については、以下のガイドを参照してください: https://docs.windsurf.com/windsurf/mcp

Smithery経由でインストール

Smithery経由で Claude Desktop 用の CircleCI MCP Server を自動的にインストールするには:

特徴

サポートされているツール

• get_build_failure_logs

  CircleCI ビルドから詳細な失敗ログを取得します。このツールは次の 3 つの方法で使用できます。

  1. プロジェクトスラッグとブランチの使用（推奨ワークフロー）:

     • まず、利用可能なプロジェクトをリストします。

       • list_followed_projectsツールを使用してプロジェクトを取得します

       • 例:「CircleCI プロジェクトの一覧を表示する」

       • 次に、プロジェクトスラッグが関連付けられているプロジェクトを選択します。

       • 例:「my-project を使ってみましょう」

     • 次に、特定のブランチのビルド失敗ログを取得するように要求します。

       • 例:「メインブランチの my-project のビルド失敗を取得する」

  2. CircleCI URL の使用:

     • 失敗したジョブのURLまたはパイプラインのURLを直接指定します

     • 例: 「 https://app.circleci.com/pipelines/github/org/repo/123からログを取得する」

  3. ローカル プロジェクト コンテキストの使用:

     • 以下を提供することで、ローカル ワークスペースから作業できます。

       • ワークスペースのルートパス

       • GitリモートURL

       • 支店名

     • 例: 「現在のブランチで最後に失敗したパイプラインを見つける」

  このツールは、次のようなフォーマットされたログを返します。

  • ジョブ名

  • ステップバイステップの実行の詳細

  • 失敗メッセージとコンテキスト

  これは特に次の場合に役立ちます:

  • 失敗したビルドのデバッグ

  • テストの失敗を分析する

  • 展開の問題の調査

  • IDEを離れずにビルドログに素早くアクセス

• find_flaky_tests

  テスト実行履歴を分析し、CircleCIプロジェクト内の不安定なテストを特定します。この機能は、https: //circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detectionで説明されている不安定なテスト検出機能を活用します。

  このツールは次の 3 つの方法で使用できます。

  1. プロジェクトスラッグの使用（推奨ワークフロー）:

     • まず、利用可能なプロジェクトをリストします。

       • list_followed_projectsツールを使用してプロジェクトを取得します

       • 例:「CircleCI プロジェクトの一覧を表示する」

       • 次に、projectSlugが関連付けられているプロジェクトを選択します。

       • 例:「my-project を使ってみましょう」

     • 次に、不安定なテストを取得するように要求します。

       • 例: 「my-project の不安定なテストを取得する」

  2. CircleCI プロジェクト URL の使用:

     • CircleCI からプロジェクト URL を直接提供します

     • 例: 「 https://app.circleci.com/pipelines/github/org/repoで不安定なテストを見つける」

  3. ローカル プロジェクト コンテキストの使用:

     • 以下を提供することで、ローカル ワークスペースから作業できます。

       • ワークスペースのルートパス

       • GitリモートURL

     • 例: 「現在のプロジェクトで不安定なテストを見つける」

  このツールは、次のような不安定なテストに関する詳細な情報を返します。

  • テスト名とファイルの場所

  • 失敗メッセージとコンテキスト

  これは次のことに役立ちます:

  • テストスイート内の信頼性の低いテストを特定する

  • テストの失敗に関する詳細なコンテキストを取得する

  • テストの改善についてデータに基づいた意思決定を行う

• get_latest_pipeline_status

  指定されたブランチの最新のパイプラインのステータスを取得します。このツールは3つの方法で使用できます。

  1. プロジェクトスラッグとブランチの使用（推奨ワークフロー）:

     • まず、利用可能なプロジェクトをリストします。

       • list_followed_projectsツールを使用してプロジェクトを取得します

       • 例:「CircleCI プロジェクトの一覧を表示する」

       • 次に、projectSlugが関連付けられているプロジェクトを選択します。

       • 例:「my-project を使ってみましょう」

     • 次に、特定のブランチの最新のパイプライン ステータスを取得するように要求します。

       • 例:「メインブランチの my-project の最新パイプラインのステータスを取得する」

  2. CircleCI プロジェクト URL の使用:

     • CircleCI からプロジェクト URL を直接提供します

     • 例: 「 https://app.circleci.com/pipelines/github/org/repoの最新パイプラインのステータスを取得する」

  3. ローカル プロジェクト コンテキストの使用:

     • 以下を提供することで、ローカル ワークスペースから作業できます。

       • ワークスペースのルートパス

       • GitリモートURL

       • 支店名

     • 例: 「現在のプロジェクトの最新のパイプラインのステータスを取得する」

  ツールは最新のパイプラインのフォーマットされたステータスを返します。

  • ワークフロー名と現在のステータス

  • 各ワークフローの所要時間

  • 作成と完了のタイムスタンプ

  • パイプライン全体の健全性

  出力例:

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

  これは特に次の場合に役立ちます:

  • 最新のパイプラインのステータスを確認する

  • 特定のブランチの最新パイプラインのステータスを取得する

  • IDEを離れずに最新のパイプラインのステータスを素早く確認

• get_job_test_results

  CircleCIジョブのテストメタデータを取得し、IDEを離れることなくテスト結果を分析できます。このツールは以下の3つの方法で使用できます。

  1. プロジェクトスラッグとブランチの使用（推奨ワークフロー）:

     • まず、利用可能なプロジェクトをリストします。

       • list_followed_projectsツールを使用してプロジェクトを取得します

       • 例:「CircleCI プロジェクトの一覧を表示する」

       • 次に、projectSlugが関連付けられているプロジェクトを選択します。

       • 例:「my-project を使ってみましょう」

     • 次に、特定のブランチのテスト結果を取得するように要求します。

       • 例:「メインブランチの my-project のテスト結果を取得する」

  2. CircleCI URL の使用:

     • 次のいずれかの形式で CircleCI URL を指定します。

       • ジョブ URL: 「 https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 」

       • ワークフロー URL: 「 https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def 」

       • パイプライン URL: 「 https://app.circleci.com/pipelines/github/org/repo/123 」

     • 例: 「 https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-defのテスト結果を取得する」

  3. ローカル プロジェクト コンテキストの使用:

     • 以下を提供することで、ローカル ワークスペースから作業できます。

       • ワークスペースのルートパス

       • GitリモートURL

       • 支店名

     • 例:「メインブランチ上の現在のプロジェクトのテスト結果を取得する」

  ツールは詳細なテスト結果情報を返します。

  • すべてのテストの概要（合計、成功、失敗）

  • 失敗したテストに関する詳細情報:

    • テスト名とクラス

    • ファイルの場所

    • エラーメッセージ

    • 実行時間

  • 成功したテストのリストとタイミング情報

  • テスト結果でフィルタリング

  これは特に次の場合に役立ちます:

  • CircleCI ウェブ UI にアクセスせずにテストの失敗を迅速に分析

  • テスト失敗のパターンの特定

  • 最適化が必要な可能性のある遅いテストを見つける

  • プロジェクト全体のテスト範囲を確認する

  • 不安定なテストのトラブルシューティング

  注: このツールを使用するには、CircleCI の設定でテストメタデータが適切に設定されている必要があります。テストメタデータの収集設定の詳細については、 https ://circleci.com/docs/collect-test-data/ をご覧ください。

• config_helper

  CircleCI の設定タスクをガイダンスと検証で支援します。このツールは以下のことに役立ちます。

  1. CircleCI 構成を検証します。

     • .circleci/config.yml の構文エラーとセマンティックエラーをチェックします

     • 例:「CircleCI の設定を検証する」

  このツールは以下を提供します:

  • 詳細な検証結果

  • 構成の推奨事項

  これは次のことに役立ちます:

  • プッシュする前に設定エラーをキャッチする

  • CircleCI の設定のベストプラクティスを学ぶ

  • 構成の問題のトラブルシューティング

  • CircleCIの機能を正しく実装する

• create_prompt_template

  AI対応アプリケーションの機能要件に基づいて、構造化されたプロンプトテンプレートを生成するのに役立ちます。このツールは以下の機能を提供します。

  1. 機能要件を構造化されたプロンプトに変換します。

     • ユーザーの要件を最適化されたプロンプトテンプレートに変換します

     • 例: 「年齢とトピック別に就寝時のお話を生成するためのプロンプトテンプレートを作成する」

  このツールは以下を提供します:

  • 構造化されたプロンプトテンプレート

  • 必要な入力パラメータを定義するコンテキストスキーマ

  これは次のことに役立ちます:

  • AIアプリケーションに効果的なプロンプトを作成する

  • 一貫した結果を得るために入力パラメータを標準化する

  • 堅牢なAI搭載機能を構築する

• recommend_prompt_template_tests

  プロンプトテンプレートのテストケースを生成し、期待通りの結果が得られるかを確認します。このツールは以下の機能を備えています。

  1. プロンプト テンプレートのテスト ケースを提供します。

     • プロンプトテンプレートとコンテキストスキーマに基づいて多様なテストシナリオを作成します

     • 例: 「就寝時のストーリープロンプトテンプレートのテストを生成する」

  このツールは以下を提供します:

  • 推奨されるテストケースの配列

  • テンプレートの堅牢性をテストするためのさまざまなパラメータの組み合わせ

  これは次のことに役立ちます:

  • プロンプトテンプレートの機能を検証する

  • 入力全体にわたって一貫したAI応答を確保する

  • エッジケースと潜在的な問題を特定する

  • AIアプリケーション全体の品質を向上

• list_followed_projects

  CircleCIでユーザーがフォローしているすべてのプロジェクトを一覧表示します。このツールは以下の機能を提供します。

  1. プロジェクトを取得して表示します:

     • ユーザーがアクセスでき、フォローしているすべてのプロジェクトを表示します

     • 各エントリにプロジェクト名とプロジェクトスラッグを提供します

     • 例:「CircleCI プロジェクトの一覧を表示する」

  ツールはフォーマットされたプロジェクトのリストを返します。出力例:

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

  これは特に次の場合に役立ちます:

  • 利用可能な CircleCI プロジェクトを特定する

  • 他の CircleCI ツールに必要な projectSlug を取得する

  • 後続の操作のためのプロジェクトの選択

  注: projectSlug (プロジェクト名ではありません) は他の多くの CircleCI ツールに必須であり、プロジェクトを選択した後にそれらのツールの呼び出しに使用されます。

• run_pipeline

  パイプラインの実行をトリガーします。このツールは次の3つの方法で使用できます。

  1. プロジェクトスラッグとブランチの使用（推奨ワークフロー）:

     • まず、利用可能なプロジェクトをリストします。

       • list_followed_projectsツールを使用してプロジェクトを取得します

       • 例:「CircleCI プロジェクトの一覧を表示する」

       • 次に、projectSlugが関連付けられているプロジェクトを選択します。

       • 例:「my-project を使ってみましょう」

     • 次に、特定のブランチに対してパイプラインを実行するように要求します。

       • 例:「メインブランチで my-project のパイプラインを実行する」

  2. CircleCI URL の使用:

     • 次のいずれかの形式で CircleCI URL を指定します。

       • ジョブ URL: 「 https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 」

       • ワークフロー URL: 「 https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def 」

       • パイプライン URL: 「 https://app.circleci.com/pipelines/github/org/repo/123 」

       • ブランチを含むプロジェクト URL: " https://app.circleci.com/projects/github/org/repo?branch=main "

     • 例: 「 https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-defのパイプラインを実行します」

  3. ローカル プロジェクト コンテキストの使用:

     • 以下を提供することで、ローカル ワークスペースから作業できます。

       • ワークスペースのルートパス

       • GitリモートURL

       • 支店名

     • 例:「メインブランチで現在のプロジェクトのパイプラインを実行する」

  このツールは、パイプラインの実行を監視するためのリンクを返します。

  これは特に次の場合に役立ちます:

  • CircleCI の Web UI にアクセスせずにパイプラインをすばやく実行

  • 特定のブランチからパイプラインを実行する

発達

はじめる

1. リポジトリをクローンします。

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

2. 依存関係をインストールします:

   pnpm install

3. プロジェクトをビルドします。

   pnpm build

Dockerコンテナの構築

次のコマンドを使用して、Docker コンテナをローカルでビルドできます。

これにより、任意の MCP クライアントで使用できるcircleci:mcp-server-circleciとしてタグ付けされた Docker イメージが作成されます。

コンテナを実行するには:

MCP Inspectorを使用した開発

MCPサーバーで反復処理を行う最も簡単な方法は、MCPインスペクターを使用することです。MCPインスペクターの詳細については、 https://modelcontextprotocol.io/docs/tools/inspectorをご覧ください。

1. 開発サーバーを起動します。

   pnpm watch # Keep this running in one terminal

2. 別のターミナルで、インスペクターを起動します。

   pnpm inspector

3. 環境を構成します。

   • インスペクターUIの環境変数セクションにCIRCLECI_TOKENを追加します。

   • トークンにはCircleCIプロジェクトへの読み取りアクセス権が必要です

   • オプションでCircleCIのベースURLを設定できます。デフォルトはhttps//circleci.comです。

テスト

• テスト スイートを実行します。

  pnpm test

• 開発中にウォッチモードでテストを実行します。

  pnpm test:watch

より詳しい貢献ガイドラインについては、 CONTRIBUTING.mdをご覧ください。