ClaudeとCircleCIを連携してビルド失敗とパイプラインを診断する
CircleCIのホスト型MCPサーバーとCLI内蔵MCPをClaude Codeとclaude.aiに繋ぎ、ビルド失敗の診断とワークフロー再実行までを扱います。
CircleCIのMCPサーバーは2種類あります。CircleCI自身がホストするサーバーと、CircleCI CLIに組み込まれたサーバーです。ビルド失敗のログ調査やワークフローの再実行は、どちらもClaudeに自然文で頼めます。違いは認証の置き場所と、扱える操作の範囲です。以前npmで配布されていたローカルMCPサーバーは非推奨になったので、これから繋ぐならこの2つのどちらかになります。
失敗の調査だけならホスト型、設定まで触るならCLI内蔵型
ホスト型はhttps://mcp.circleci.com/v1/mcpで公開されています。インストールは要らず、OAuth2か個人APIトークンで認証します。CLI内蔵型はcircleciコマンドの一部として手元のマシンで動きます。
どちらを繋ぐか
ホスト型MCP
CircleCIが運用するサーバーに、HTTPSで接続します。実行(run)の一覧、ワークフロー、ジョブのログ、失敗したテスト、再実行とキャンセルが中心です。リモートMCPサーバーにしか対応しないAIアシスタントでも使えます。
CLI内蔵MCP
circleci auth loginのセッションかCIRCLE_TOKEN環境変数を使い、手元で動きます。configの検証と生成、orbの公開、Rego方式のポリシー、セルフホストランナー、Docker Layer Cache、コンテキストと環境変数の管理まで担います。CLIのコマンドがそのままツールになります。認証情報を開発者のマシンに置きたい組織向けです。
2つは独立していて、片方を繋いでももう片方は外れません。日々の障害対応はホスト型、.circleci/config.ymlの編集や運用作業はCLI内蔵型、という並べ方ができます。
config検証の扱いは、公式の2ページで説明が分かれます。CircleCIのドキュメントは、ホスト型を実行の観察と操作に絞った道具とし、config作成をCLI内蔵型の守備範囲に置いています。一方、Claudeのコネクタページのツール一覧には、CircleCI側の表に出てこないvalidate_configがあります。CLI内蔵型なら、configの検証がドキュメント上も守備範囲です。ホスト型で今使えるツールは、接続後にClaudeへ一覧を聞くと実際の名前で分かります。
Claude CodeにホストMCPを繋ぐ
接続は4ステップです。Claude Codeの通常のMCP追加と同じ流れで、OAuth2のサインインだけがブラウザで挟まります。
Claude Codeでの接続
- 1
旧サーバーが残っていたら外す
npmの
@circleci/mcp-server-circleciをcircleci-mcp-serverという名前で登録していた場合は、先にclaude mcp remove circleci-mcp-serverで外します。CircleCIのドキュメントも、新しい接続の前に旧サーバーを外すよう求めています。 - 2
ホスト型を追加する
claude mcp add --transport httpでURLを指定します。コマンドは下に載せています。 - 3
OAuth2でサインインする
セッション内で
/mcpを実行し、circleci-mcp-serverを選んでAuthenticateを押します。ブラウザでCircleCIにサインインすると完了です。 - 4
疎通を確かめる
helloツールは、ホスト型への接続を確認するためのものです。CircleCIのドキュメントの表に載っているツールで、Claudeのコネクタページの一覧には出てこないため、claude.aiから繋いだ場合は使えない可能性があります。
claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcpOAuth2に対応しないクライアントや、無人で動かす用途では、個人APIトークンをヘッダーで渡します。CircleCIはOAuth2を勧めています。トークンを保管せずに済み、アクセスの取り消しも設定を書き換えずにできるからです。
claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp \
--header "Authorization: Bearer <your-circleci-token>"設定がどこに書かれるかを実機で見る
Claude Code v2.1.289でclaude mcp addを実行すると、次のように出力されます。既定のスコープはlocalで、そのプロジェクトの自分専用の設定に入ります。
$ claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp
Added HTTP MCP server circleci-mcp-server with URL: https://mcp.circleci.com/v1/mcp to local configチームで共有するなら--scope projectを付けます。設定はプロジェクト直下の.mcp.jsonに書かれ、リポジトリにコミットできます。ここでトークンを直書きすると、そのままリポジトリに残ります。実行時の出力はヘッダーの値を[REDACTED]と伏せて表示しますが、.mcp.jsonのファイルには書いた文字列がそのまま入ります。
$ claude mcp add --scope project --transport http circleci-token https://mcp.circleci.com/v1/mcp \
--header 'Authorization: Bearer ${CIRCLECI_TOKEN}'
Added HTTP MCP server circleci-token with URL: https://mcp.circleci.com/v1/mcp to project config
Headers: {
"Authorization": "[REDACTED]"
}
File modified: .mcp.jsonトークンは${変数名}の形で書くと、.mcp.jsonに実際の値を残さずに済みます。headersの中でも環境変数の展開が効きます。変数が未設定でも設定は読み込まれ、${変数名}の文字列のまま送られるので、claude mcp listの警告を見て気づく形になります。
claude.aiとClaude Desktopにはディレクトリから追加する
CircleCIのホスト型MCPは、Claudeのコネクタディレクトリに「Anthropic verified」として載っています。掲載は2026年7月です。サーバーURLの手入力は要りません。「Customize > Connectors」でCircleCIを探して追加し、ブラウザでサインインすれば済みます。ディレクトリを使わずにURLを自分で入れる場合は、カスタムコネクタの扱いです。
カスタムコネクタの追加には、プランごとに条件があります。個人のPro・Maxは「Customize > Connectors」から「+ Add」→「Add custom connector」で、URLにhttps://mcp.circleci.com/v1/mcpを入れます。Team・Enterpriseでは追加できる人が限られます。
- Team: OwnerとPrimary Ownerが「Organization settings > Connectors」から追加し、メンバーは各自が接続します
- Enterprise: Owner、Primary Owner、LibrariesのManage権限を持つカスタムロールの人が追加できます
- Free: カスタムコネクタは1つまでです
追加後は会話画面左下の「+」→「Connectors」で、そのやり取りだけ有効にできます。
接続の経路にも注意が要ります。カスタムコネクタは、手元のPCではなくAnthropicのクラウドからMCPサーバーへ接続します。Claude DesktopやCoworkでも同じです。CircleCIのホスト型は公開インターネット上にあるので問題になりません。社内ネットワークの中にあるMCPサーバーを同じやり方で繋ぐ場合は、Anthropicのクラウドから届く経路が必要になります。
CLI内蔵MCPをローカルで有効にする
CircleCI CLIを入れ、circleci auth loginを済ませるか、CIRCLE_TOKEN環境変数を設定すると、1コマンドで有効にできます。
circleci mcp claude enable # Claude Desktop
circleci mcp cursor enable # Cursor
circleci mcp vscode enable # VS CodeCircleCIのページがenableの対象として挙げるのは、この3つです。このうちcircleci mcp claude enableは、Claude Desktop向けのコマンドです。Claude Codeには、手動起動のコマンドを自分で登録します。標準入出力で動くcircleci mcp startと、HTTPでストリーミングするcircleci mcp streamがあります。stdioで動くものは、Claude Code側ではstdioサーバーとして登録する形になります。
claude mcp add circleci-cli -- circleci mcp start止めるときは、enableをdisableに替えます。
旧npm版から移ると、ツールの顔ぶれが変わる
旧パッケージ@circleci/mcp-server-circleciのリポジトリは、READMEの冒頭で非推奨を告げ、アーカイブ予定としています。理由として挙げているのは、メンテナンスされないサーバーが個人APIトークンを持ったまま動き続けるのは勧められない、という点です。組織のトークンを仲介する自己管理型のstart=remoteを使っていた場合は、ホスト型がその直接の置き換えになります。
旧版のツールと、今の公式ページの一覧を並べると、名前も範囲も変わっています。用途が近いものを同じ行に置きました。
| 旧パッケージのツール | CircleCIドキュメントの表 | Claudeコネクタページの一覧 |
|---|---|---|
get_build_failure_logs | CircleCIドキュメントの表get_job_logs | Claudeコネクタページの一覧get_job_logs |
get_job_test_results | CircleCIドキュメントの表list_job_tests | Claudeコネクタページの一覧list_job_tests |
get_latest_pipeline_status | CircleCIドキュメントの表list_runs / get_run | Claudeコネクタページの一覧list_runs / get_run |
list_artifacts | CircleCIドキュメントの表list_artifacts | Claudeコネクタページの一覧list_job_artifacts |
rerun_workflow | CircleCIドキュメントの表rerun_workflow | Claudeコネクタページの一覧rerun_workflow |
config_helper | CircleCIドキュメントの表なし(CLI内蔵MCPの領分) | Claudeコネクタページの一覧validate_config |
run_rollback_pipeline | CircleCIドキュメントの表なし | Claudeコネクタページの一覧rollback_deploy_component |
find_flaky_tests | CircleCIドキュメントの表なし | Claudeコネクタページの一覧なし |
find_underused_resource_classes | CircleCIドキュメントの表なし | Claudeコネクタページの一覧なし |
最後の2行は注意が要ります。フレーキーテストの検出は、どちらのページのツール名にも出てきません。リソースクラスの過剰割り当てについても、専用の検出ツールは載っていません。ただしコネクタページの一覧にはget_job_resource_usageがあり、使用率の取得はこれが担う可能性があります。説明文には、使われていないリソースクラスの特定が機能として書かれています。同等の分析をMCPに期待しすぎず、必要ならCLI内蔵MCP経由のcircleci apiでAPIを直接呼びます。
同じツールがページごとに別の名前で載っている点も見逃せません。CircleCIの表にあるワークフロー一覧はlist_workflows、ジョブ一覧はlist_jobsですが、コネクタページではlist_run_workflowsとlist_workflow_jobsです。依頼文にツール名を書き込むと、名前が違ったときに通りません。依頼は「このブランチの最後の実行が落ちた原因は?」のように結果で書き、ツールの選択はClaudeに任せます。
診断はどういう順でツールを辿るか
ホスト型のツールは鎖のようにつながっています。CircleCIのドキュメントでは、list_runsが実行のIDを返し、get_run、list_workflows、list_jobsと下りて、最後にget_job、get_job_logs、list_artifacts、list_job_testsへ分かれると説明しています。
失敗した実行を調べるときの流れ
- 1
実行を探す
list_runsで、ブランチや実行の状態を絞って一覧を取ります。プロジェクトはスラッグ(gh/org/repo)かUUIDで指定します。 - 2
ワークフローとジョブを辿る
get_runで失敗した実行の概要を見て、list_workflowsとlist_jobsで、どのジョブが落ちたかを絞ります。 - 3
ログかテストを読む
get_job_logsは、ステップを指定しなければ失敗したステップを自動で読みます。テストの失敗ならlist_job_testsで、失敗したテストが返ります。
get_jobはステップごとの終了コードまで返します。ログが長いジョブで、どのステップが非ゼロで終わったかを先に知りたいときに向く入口です。list_job_testsの既定は失敗したテストだけで、成功やスキップも含めたいときはallを指定します。
再実行には2通りあります。rerun_workflowは既定で全ジョブを最初からやり直します。from_failedを指定すると、失敗したジョブとその下流だけが再実行され、成功済みのジョブは使い回されます。「失敗したジョブだけやり直して」と頼めば、この指定で再実行できます。cancel_workflowは実行中のワークフローを止めます。
利用状況の集計にも使えます。download_usage_dataは、組織のスラッグかUUIDと、最長31日の期間を指定すると、CSVファイルとして書き出します。
つまずいたときの切り分け
接続が切れたとき、まず見る場所
OAuth2で繋いでいる
Claude Codeなら
/mcpでcircleci-mcp-serverを選び、再認証します。CircleCIのドキュメントも、まず再認証を勧めています。APIトークンで繋いでいる
トークンが失効していないか、対象プロジェクトにアクセスできるユーザーのものかを見ます。
CLI内蔵MCPで繋いでいる
MCPの設定でなく、CLIのログイン状態(
circleci auth login)かCIRCLE_TOKENの値を先に確かめます。
ツールの一覧が古いままのときは、CircleCI側で新しいツールが出たあとにMCPホストを再起動するか、接続をやり直します。CLI内蔵MCPのツールはCLI全体に対応しているため、CircleCIのページには固定の一覧がありません。circleci help referenceが、呼び出せるコマンドを全部出力します。
同じ名前のサーバーが複数のスコープに別のエンドポイントで定義されていると、Claude Codeはclaude mcp listと/mcpで警告します。旧パッケージと新しいURLの登録が重なる場合も、この点に注意します。OAuthのサインインはエンドポイントごとに保存されるので、片方で認証しても、別の定義が読み込まれるプロジェクトでは改めてサインインが要ります。不要な定義はclaude mcp remove <名前> --scope <スコープ>で消します。
まとめ
日々の失敗調査と再実行はホスト型、configとorbの編集やランナー管理まで頼むならCLI内蔵型、と分けて繋ぎます。ツール名は公式ページ同士でも揺れているので、依頼は結果で書き、名前の指定はClaudeに任せるのが無難です。ほかのCI/CD向けMCPは、Terraform MCPサーバーやGitHub ActionsとClaude Codeの連携でも同じ設定の型で繋げます。モバイルアプリのビルドならBitrise MCPの接続と失敗調査も同じ流れです。カスタムコネクタの権限設計に迷ったら、Anthropic Connectors Directoryへの登録手順も参考になります。パイプラインの実行まで任せる別のCI/CDなら、Harness MCPサーバーの接続と権限設計があります。