CircleCI

前提条件：

• CircleCI Personal API トークン（詳細）
• NPX: Node.js >= v18 と 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 トークン（詳細）
• NPX: Node.js >= v18 と 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 トークン（詳細）
• NPX: Node.js >= v18 と 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 トークン（詳細）
• NPX: Node.js >= v18 と 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 トークン（詳細）
• NPX: Node.js >= v18 と 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 トークン（詳細）
• NPX: Node.js >= v18 と 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 トークン（詳細）
• NPX: Node.js >= v18 と 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 サーバーを自動的にインストールするには：

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

例: 「私のブランチで最新の失敗したパイプラインを探してログを取得する」 — その他の例はウィキを参照してください。

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 ファイルを提供します。

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

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 で >= 18.0.0 を確認してください
• 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 コンソールからの関連エラーメッセージを共有してください