CircleCI

前提条件:

• CircleCI Personal API token (詳細)
• NPX: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 および pnpm
• Docker: Docker

ローカル MCP サーバーで NPX を使用する

Cursor の MCP 設定に以下を追加します:

{
  "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 は任意です — オンプレミスのお客様のみ必須です。 MAX_MCP_OUTPUT_LENGTH は任意です — MCP レスポンスの最大出力長 (デフォルト: 50000)。

ローカル MCP サーバーで Docker を使用する

Cursor の MCP 設定に以下を追加します:

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

セルフマネージドリモート MCP サーバーを使用する

セルフマネージドリモート MCP サーバーを参照してください。ユーザーごとのクライアント設定を使用し、Cursor の MCP 設定 (Cursor Settings → MCP) に追加します。

前提条件:

• CircleCI Personal API token (詳細)
• NPX: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 および pnpm
• Docker: Docker

ローカル MCP サーバーで NPX を使用する

プロジェクト内の .vscode/mcp.json に以下を追加します:

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

💡 入力はサーバーの初回起動時に求められ、その後 VS Code によって安全に保存されます。

ローカル MCP サーバーで Docker を使用する

プロジェクト内の .vscode/mcp.json に以下を追加します:

{
  "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}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

セルフマネージドリモート MCP サーバーを使用する

セルフマネージドリモート MCP サーバーを参照してください。.vscode/mcp.json でユーザーごとのクライアント設定を使用します。

前提条件:

• CircleCI Personal API token (詳細)
• NPX: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 および pnpm
• Docker: Docker

ローカル MCP サーバーで NPX を使用する

claude_desktop_config.json に以下を追加します:

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

ローカル MCP サーバーで Docker を使用する

claude_desktop_config.json に以下を追加します:

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

セルフマネージドリモート MCP サーバーを使用する

セルフマネージドリモート MCP サーバーを参照してください。Claude Desktop および CLI クライアントに示すようにラッパースクリプトを作成し、claude_desktop_config.json をそのスクリプトに向けます。

設定ファイルを見つけるか作成するには、Claude Desktop の設定を開き、左サイドバーの Developer をクリックしてから Edit Config をクリックします。設定ファイルの場所は次のとおりです:

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

詳細情報: https://modelcontextprotocol.io/quickstart/user

前提条件:

• CircleCI Personal API token (詳細)
• NPX: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 および pnpm
• Docker: Docker

ローカル MCP サーバーで NPX を使用する

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

ローカル MCP サーバーで Docker を使用する

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

セルフマネージドリモート MCP サーバーを使用する

セルフマネージドリモート MCP サーバーおよびそこの Claude Code クライアント設定を参照してください。

前提条件:

• CircleCI Personal API token (詳細)
• NPX: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 および pnpm
• Docker: Docker

ローカル MCP サーバーで NPX を使用する

Windsurf の mcp_config.json に以下を追加します:

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

ローカル MCP サーバーで Docker を使用する

Windsurf の mcp_config.json に以下を追加します:

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

セルフマネージドリモート MCP サーバーを使用する

セルフマネージドリモート MCP サーバーを参照してください。Windsurf の mcp_config.json でユーザーごとのクライアント設定を使用します。

詳細情報: https://docs.windsurf.com/windsurf/mcp

前提条件:

• CircleCI Personal API token (詳細)
• NPX: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 および pnpm

Amazon Q Developer の MCP クライアント設定は、mcp.json という名前のファイルに JSON 形式で保存されます。2 つのレベルの設定がサポートされています:

• グローバル: ~/.aws/amazonq/mcp.json — すべてのワークスペースに適用されます
• ワークスペース: .amazonq/mcp.json — 現在のワークスペースに固有です

両方のファイルが存在する場合、その内容がマージされます。競合する場合は、ワークスペースの設定が優先されます。

ローカル MCP サーバーで NPX を使用する

~/.aws/amazonq/mcp.json を編集するか、.amazonq/mcp.json を次の内容で作成します:

{
  "mcpServers": {
    "circleci-local": {
      "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"
      },
      "timeout": 60000
    }
  }
}

セルフマネージドリモート MCP サーバーを使用する

セルフマネージドリモート MCP サーバーを参照してください。Claude Desktop および CLI クライアントに示すようにラッパースクリプトを使用し、q mcp add で登録します。

前提条件:

• CircleCI Personal API token (詳細)
• NPX: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 および pnpm

ローカル MCP サーバーで NPX を使用する

~/.aws/amazonq/mcp.json を編集するか、.amazonq/mcp.json を次の内容で作成します:

{
  "mcpServers": {
    "circleci-local": {
      "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"
      },
      "timeout": 60000
    }
  }
}

セルフマネージドリモート MCP サーバーを使用する

セルフマネージドリモート MCP サーバーを参照してください。Claude Desktop および CLI クライアントに示すようにラッパースクリプトを使用し、MCP 設定 UI から追加します:

1. MCP 設定 UI にアクセスする
2. + 記号を選択します
3. スコープを選択します: global または local
4. 名前を入力します (例: circleci-remote-mcp)
5. トランスポートプロトコルを選択します: stdio
6. スクリプトへのコマンドパスを入力します
7. Save をクリックします

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

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

例: 「自分のブランチで最新の失敗したパイプラインを見つけてログを取得する」 — その他の例については wiki を参照してください。

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

ガイダンスと検証を提供することで、CircleCI の設定タスクを支援します。

• .circleci/config.yml の構文エラーとセマンティックエラーを検証します
• 詳細な検証結果と設定の推奨事項を提供します
• 例: 「私の CircleCI 設定を検証する」

指定された組織の使用状況データを CircleCI Usage API からダウンロードします。柔軟な日付入力 (例: 「2025年3月」や「先月」) を受け付けます。クラウド専用の機能です。

オプション 1: 以下を指定して新しいエクスポートジョブを開始します:

• orgId、startDate、endDate (最大 32 日)、outputDir

オプション 2: 以下を指定して既存のエクスポートジョブを確認/ダウンロードします:

• orgId、jobId、outputDir

指定された期間の CircleCI 使用状況データを含む CSV ファイルを返します。

[!NOTE] 使用状況データは、コスト最適化分析のために find_underused_resource_classes ツールに渡すことができます。

テスト実行履歴を分析することで、CircleCI プロジェクト内の不安定なテストを特定します。CircleCI の 不安定なテスト検出機能 を活用します。

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

1. プロジェクトスラッグを使用する (推奨):

   • まず list_followed_projects を使用してプロジェクトを取得し、次に:
   • 例: 「my-project の不安定なテストを取得する」

2. CircleCI プロジェクト URL を使用する:

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

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

   • ワークスペースルートと git リモート URL を指定することで、ローカルワークスペースから動作します
   • 例: 「現在のプロジェクトの不安定なテストを見つける」

出力モード:

• テキスト (デフォルト): 不安定なテストの詳細をテキスト形式で返します
• ファイル (FILE_OUTPUT_DIRECTORY 環境変数が必要): 不安定なテストの詳細を含むディレクトリを作成します

CircleCI 使用状況データの CSV ファイルを分析し、平均または最大の CPU/RAM 使用率が指定されたしきい値 (デフォルト: 40%) を下回るジョブを見つけます。

download_usage_api_data から取得した CSV ファイルを指定してください。

プロジェクトとワークフローごとに整理された、使用率の低いジョブの Markdown リストを返します — コスト最適化の機会を特定するのに役立ちます。

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

1. プロジェクトスラッグとブランチを使用する (推奨):

   • まず list_followed_projects を使用してプロジェクトを取得し、次に:
   • 例: 「main ブランチの my-project のビルド失敗を取得する」

2. CircleCI URL を使用する:

   • 失敗したジョブの URL またはパイプラインの URL を直接指定します
   • 例: 「https://app.circleci.com/pipelines/github/org/repo/123 からログを取得する」

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

   • ワークスペースルート、git リモート URL、ブランチ名を指定することで、ローカルワークスペースから動作します
   • 例: 「現在のブランチで最新の失敗したパイプラインを見つける」

このツールは、以下を含む整形されたログを返します:

• ジョブ名
• ステップごとの実行の詳細
• 失敗メッセージとコンテキスト

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

1. プロジェクトスラッグとブランチを使用する (推奨):

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

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

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

   • ワークスペースルート、git リモート URL、ブランチ名を指定することで、ローカルワークスペースから動作します

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

• すべてのテストの概要 (合計、成功、失敗)
• 失敗したテストの詳細情報: 名前、クラス、ファイル、エラーメッセージ、所要時間
• タイミング付きの成功したテストのリスト
• テスト結果によるフィルタリング

[!NOTE] テストメタデータは CircleCI 設定で構成する必要があります。セットアップ手順については テストデータの収集 を参照してください。

1. プロジェクトスラッグとブランチを使用する(推奨):

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

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

CircleCI ジョブによって生成されたアーティファクトの一覧を取得します。このツールは3つの方法で使用できます:

1. プロジェクトスラッグとブランチを使用する(推奨):

   • まず list_followed_projects を使用してプロジェクトを取得し、次に:
   • 例:「main ブランチの my-project のアーティファクトを一覧表示する」

2. CircleCI URL を使用する:

   • ジョブ URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
   • ワークフロー URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
   • パイプライン URL: https://app.circleci.com/pipelines/gh/organization/project/123

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

   • ワークスペースルート、git リモート URL、ブランチ名を指定することで、ローカルワークスペースから動作します

用途:

• ビルドアーティファクト(バイナリ、レポート、ログ)のダウンロード URL の検索
• パイプライン実行によって生成されたアーティファクトの確認

環境内の特定の CircleCI コンポーネントのすべてのバージョンを一覧表示します。デプロイステータス、コミット情報、タイムスタンプが含まれます。

コンポーネントと環境が指定されていない場合、ツールは選択を促します。

用途:

• 現在稼働中のバージョンの特定
• ロールバック操作の対象バージョンの選択
• デプロイの詳細(パイプライン、ワークフロー、ジョブ)の取得

ユーザーが CircleCI でフォローしているすべてのプロジェクトを一覧表示します。

• アクセス権のあるすべてのプロジェクトとその projectSlug を表示します
• 例:「自分の CircleCI プロジェクトを一覧表示する」

出力例:

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

[!NOTE] 他の多くの CircleCI ツールでは、プロジェクト名ではなく projectSlug が必要です。

ワークフローを最初から、または失敗したジョブから再実行します。

新しく作成されたワークフローの ID と、それを監視するためのリンクを返します。

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

1. プロジェクトスラッグとブランチを使用する(推奨):

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

2. CircleCI URL を使用する:

   • パイプライン URL、ワークフロー URL、ジョブ URL、またはブランチ付きのプロジェクト URL
   • 例:「https://app.circleci.com/pipelines/github/org/repo/123 のパイプラインを実行する」

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

   • ワークスペースルート、git リモート URL、ブランチ名を指定することで、ローカルワークスペースから動作します

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

CircleCI プロジェクトのロールバックをトリガーします。このツールは次の手順を対話的に案内します:

1. プロジェクトの選択 — フォローしているプロジェクトを一覧表示し、選択できます
2. 環境の選択 — 利用可能な環境を一覧表示します(1つだけの場合は自動選択)
3. コンポーネントの選択 — 利用可能なコンポーネントを一覧表示します(1つだけの場合は自動選択)
4. バージョンの選択 — 利用可能なバージョンを表示し、ロールバックの対象を選択します
5. ロールバックモードの検出 — ロールバックパイプラインが設定されているか確認します
6. ロールバックの実行 — 2つのオプション:
   • パイプラインロールバック: ロールバックパイプラインをトリガーします
   • ワークフロー再実行: ワークフロー ID を使用して以前のワークフローを再実行します
7. 確認 — 実行前に概要をまとめて確認します

よくある問題:

1. パッケージキャッシュをクリアする:

   npx clear-npx-cache
   npm cache clean --force
   

2. 最新バージョンを強制する: 設定に @latest を追加します:

   "args": ["-y", "@circleci/mcp-server-circleci@latest"]
   

3. IDE を完全に再起動する(ウィンドウのリロードだけでは不十分)

• 無効なトークンエラー: Personal API Tokens で CIRCLECI_TOKEN を確認してください
• 権限エラー: トークンにプロジェクトへの読み取りアクセス権があることを確認してください
• 環境変数が読み込まれない: echo $CIRCLECI_TOKEN(Mac/Linux)または echo %CIRCLECI_TOKEN%(Windows)でテストしてください

• ベース URL: CIRCLECI_BASE_URL が https://circleci.com であることを確認してください
• 企業ネットワーク: ファイアウォールの内側にいる場合は npm プロキシ設定を構成してください
• ファイアウォールによるブロック: セキュリティソフトウェアがパッケージのダウンロードをブロックしていないか確認してください

• Node.js バージョン: node --version で ^22.23.4 || ^24.22.1 || >=26.12.1 を満たしていることを確認してください
• Node.js の更新: 互換性の問題が発生している場合は最新の LTS を検討してください
• パッケージマネージャー: npm/pnpm が動作していることを確認してください: npm --version

• 設定ファイルの場所: お使いの OS のパスを再確認してください
• 構文エラー: 設定ファイルの JSON 構文を検証してください
• コンソールログ: 具体的なエラーについては IDE の開発者コンソールを確認してください
• 別の IDE を試す: 問題を切り分けるため、別のサポート対象エディタでテストしてください

プロセスがハングする場合 — 既存の MCP プロセスを強制終了します:

# Mac/Linux:
pkill -f "mcp-server-circleci"

# Windows:
taskkill /f /im node.exe

ポートの競合: 接続がブロックされているように見える場合は IDE を再起動してください。

• パッケージを直接テストする: npx @circleci/mcp-server-circleci@latest --help
• 詳細ログ: DEBUG=* npx @circleci/mcp-server-circleci@latest
• Docker フォールバック: npx が継続的に失敗する場合は Docker インストールを試してください

さらにサポートが必要ですか?

1. 同様の問題がないか GitHub Issues を確認してください
2. 問題を報告する際は、OS、Node のバージョン、IDE を含めてください
3. IDE コンソールから関連するエラーメッセージを共有してください