ClaudeとCircleCIを連携してビルド失敗とパイプラインを診断する

CircleCIはMCPサーバーを2種類提供しています。CircleCI自身がホストするサーバーと、CircleCI CLIに組み込まれたサーバーです。どちらもビルド失敗のログ調査やワークフローの再実行を自然文でClaudeに任せられますが、認証方法と扱える操作範囲が違います。以前npmで配布されていたローカルMCPサーバーはすでに非推奨になったため、これから繋ぐならこの2つのどちらかを選びます。

ホスト型とCLI内蔵型、どちらを繋ぐか

CircleCIのホスト型MCPサーバーはhttps://mcp.circleci.com/v1/mcpで公開されており、インストール不要でOAuth2かAPIトークンで認証します。日々の障害診断はこちらが基本です。一方CLI内蔵型はcircleciコマンドの一部として自分のマシン上で動き、circleci auth loginのセッションをそのまま使います。

両者は独立していて、片方を繋いでももう片方は無効になりません。用途で使い分けます。

CircleCIの公式ドキュメントも、config生成やorb管理などCLIコマンド全体を使いたい場合はCLI内蔵型を、失敗調査だけならホスト型を勧めています。

前提条件と認証方法を確認する

CircleCIは可能な限りOAuth2認証を勧めています。トークンをコピーして保管する必要がなく、アクセスの取り消しや再発行も設定を変えずに行えるためです。API Tokenを使う設定は、OAuth2に対応しないクライアントや、無人で動かすヘッドレス用途に限ります。

Claude CodeにホストMCPサーバーを繋ぐ

Claude CodeからCircleCIのホスト型MCPサーバーに繋ぐには、次のコマンドを実行します。

claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp

追加後にセッション内で/mcpを実行し、circleci-mcp-serverを選んでAuthenticateを押すとブラウザでOAuth2サインインが始まります。API Tokenを使う場合は、認証ヘッダーをコマンドラインで直接渡します。

claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp \
  --header "Authorization: Bearer <your-circleci-token>"

以前npmで配布されていた@circleci/mcp-server-circleciをClaude Codeに登録済みの場合は、切り替え前にclaude mcp remove circleci-mcp-serverで外しておきます。このパッケージは非推奨化され、リポジトリはアーカイブ予定です。個人のCircleCI API Tokenを保持したまま動き続けるメンテナンスされていないサーバーを使い続けるのは、CircleCI自身が推奨していません。

なぜホスト型とCLI内蔵型の2本立てになったか

旧npmパッケージには、組織のトークンを仲介するネットワーク公開型サービスとして動かすstart=remoteという自己管理モードもありました。この用途は今回のホスト型MCPサーバーがそのまま代替します。CircleCI自身がホストとメンテナンスを引き受けるため、ネットワーク公開サービスを自組織で運用し続ける必要がなくなります。

残る用途はローカル実行だけです。ここはCLIに機能を統合し、config authoringやorb管理までを1つのバイナリの中で完結させました。1つのnpmパッケージが担っていた「個人利用・チーム共有・CLI操作」という3つの役割を、ホスト型・自己管理・CLI内蔵の3つに再編した形です。認証情報の置き場所とメンテナンス責任の所在が、旧パッケージより明確になっています。

claude.ai・Claude Desktop・Coworkにカスタムコネクタとして繋ぐ

CircleCIはclaude.com/connectorsのディレクトリには掲載されていません。そのため接続はカスタムコネクタの扱いになり、表示名も「Custom」ラベルになります。個人のPro・Maxプランでは「Customize > Connectors」から「+」→「Add custom connector」を選び、サーバーURLにhttps://mcp.circleci.com/v1/mcpを入力して追加します。Team・Enterpriseプランでは、まずOwnerが「Organization settings > Connectors」から同じURLで組織に追加し、メンバーが個別に「Customize > Connectors」から接続する流れになります。

追加が終わったら、会話画面左下の「+」→「Connectors」でトグルをオンにすると、そのやり取りで使えるようになります。

CLI内蔵MCPをローカルで有効化する

CircleCI CLIがインストール済みでcircleci auth login済みなら、CLI内蔵MCPは1コマンドで有効化できます。

circleci mcp claude enable

このコマンドはClaude Desktop向けの設定を書き込むもので、Claude Codeを自動設定するものではない点に注意します。Claude Codeから使う場合は、標準入出力(stdio)でサーバーを起動するcircleci mcp start、またはHTTPでストリーミングするcircleci mcp streamを使い、Claude Code側のMCP設定として個別に登録します。

CircleCIのMCPで何ができるか

ホスト型MCPサーバーが公開する主なツールです。list_runsが返すIDをget_runに渡し、そこからlist_workflows→list_jobs→get_job_logsと繋いでいく形で、実行の一連の流れを1つの会話で辿れます。

CLI内蔵MCPはこれに加えて、config.ymlのバリデーションと生成、orbの作成・公開・差分確認、Rego方式のポリシーのテストと評価、セルフホストランナーのリソースクラス管理、Docker Layer Cacheのパージまで、CircleCI CLIの全コマンドをツールとして公開します。

診断を効率よく進めるための質問の仕方

CircleCIのMCPサーバーは、質問が具体的なほど無駄な往復なしに答えを返します。「ビルドを確認して」ではなく、ブランチや実行、ワークフロー、ジョブを名指しした質問にすると、Claudeが最初から正しいツールを選べます。

• 「このブランチの最後の実行はなぜ失敗した?」のように対象を具体的に絞る
• list_runsからget_run、list_workflows、get_job_logsまでの複数ツール呼び出しはClaudeに任せ、欲しい結果だけを伝える
• 実際に典型的なやり取りとしては、失敗した実行を尋ねる→原因になったジョブのログをClaudeが特定する→修正案が提示される、という流れになります。再実行やキャンセルのような書き込み系ツールを呼ぶ前は、何を実行しようとしているか確認してから許可します。共有プロジェクトや本番向けパイプラインではこの確認を省きません
• 用途に応じてホスト型とCLI内蔵型を使い分ける(前述の早見表を参照)

よくあるつまずき

npmの旧パッケージが公開していたfind_flaky_tests(フレーキーテスト検出)やfind_underused_resource_classes(リソースクラスの過剰割り当て検出)は、現行のホスト型MCPサーバーには引き継がれていません。同等の分析が必要な場合は、CLI内蔵MCP経由でcircleci apiから直接APIを呼ぶか、Web UIのInsightsを使います。

OAuth2接続が急に失敗するようになったら、まず認証切れを疑います。Claude Codeなら/mcpを実行しcircleci-mcp-serverを選んで再認証します。API Tokenで繋いでいる場合は、トークンが失効していないか、対象プロジェクトへのアクセス権を持つユーザーのものかを確認します。CLI内蔵MCPが繋がらないときは、MCPサーバー自体でなくCLIの認証セッション(circleci auth login)を先に見直します。

ツールの一覧が更新されないと感じたら、CircleCIが新しいツールをリリースした後にMCPホストを再起動するか、サーバーへの接続をやり直します。CLI内蔵MCPで使えるコマンドの全量はcircleci help referenceで確認でき、固定リストとしては公開されていません。

テストの失敗調査でも同じ流れが使えます。「そのジョブでどのテストが落ちた?」と尋ねると、list_job_testsが失敗したテストと失敗メッセージを返し、Claudeがその内容から原因と修正案をまとめます。デフォルトでは失敗したテストだけを返すため、成功・スキップまで含めた全件が欲しいときはその旨を伝えます。

まとめ

日常的な障害診断はホスト型MCPサーバー、config.ymlやorbの編集・セルフホストランナーの管理まで含めるならCLI内蔵MCPを選びます。npm版の@circleci/mcp-server-circleciはすでに非推奨で、個人トークンを持ったまま動き続けるサーバーを残すのは避けます。Terraform MCPサーバーやGitHub ActionsとClaude Codeの連携のように、他のCI/CD向けMCPサーバーも同じ設定パターンで繋げます。カスタムコネクタの権限設計に迷ったら、Anthropic Connectors Directoryへの登録手順も参考になります。