Claude Media
ClaudeとBuildkiteを連携してパイプラインとジョブログを調査する
Claude CodeMCPClaude連携チュートリアル

ClaudeとBuildkiteを連携してパイプラインとジョブログを調査する

BuildkiteのMCPサーバーをClaude Codeとclaude.aiに繋ぎ、リモート型とローカル型の使い分け、ログ検索、非特権コンテナでの安全な運用を扱います。

読了目安 約13分

Buildkiteはオープンソースの公式MCPサーバーを提供しており、パイプラインやビルド、ジョブのデータをAIアシスタントから扱えるようにします。接続先はリモート(Buildkiteがホスト)とローカル(自分で動かす)の2種類があり、Promise Job Failureのような実行中ジョブの失敗兆候まで拾える設計です。ここではClaude Code・claude.ai双方の接続手順と、ローカル実行を選ぶ場合の安全な運用を扱います。

リモートMCPサーバーとローカルMCPサーバー、どちらを使うか

Buildkiteのリモート型はhttps://mcp.buildkite.com/mcpで公開され、Buildkiteユーザーアカウントに基づく短命なOAuthトークンで認証します。インストールも更新作業も不要で、Buildkiteが加える新機能は自動的に反映されます。対して自分のマシンやコンテナで直接動かすローカル型は、実行するMCPサーバーのバージョンを固定できるため、Buildkiteパイプライン自体からAIエージェントとして呼び出す自動化ワークフローに向いています。

用途リモートMCPローカルMCP
個人利用・対話的な調査リモートMCP◎ 推奨ローカルMCP△ トークン管理の手間
Buildkiteパイプラインからの自動起動リモートMCP△ 対話認証を完了できないローカルMCP◎ バージョン固定で結果が安定
APIトークンの管理責任リモートMCPBuildkite側の短命トークンローカルMCP自分でAPIアクセストークンを保管
ソフトウェアの更新リモートMCP自動ローカルMCP自分でアップグレード
REST APIレート制限リモートMCPリモートMCP専用の別枠ローカルMCP組織の通常のREST APIレート制限を消費

読み取り専用に絞りたい場合はhttps://mcp.buildkite.com/mcp/readonly、ヘッドレスなエージェントやバックグラウンドサービスでAPIトークンを直接渡したい場合はhttps://mcp.buildkite.com/directという別エンドポイントも用意されています。

Claude Codeにリモートサーバーを繋ぐ

Claude Codeのインストール後、次のコマンドでBuildkiteのリモートMCPサーバーを追加します。

claude mcp add --transport http buildkite https://mcp.buildkite.com/mcp

追加後は初回接続時にOAuthのサインインフローが始まり、Buildkiteの自分のユーザーアカウントで認証します。読み取り専用版やAPIトークン直渡し版に切り替えたい場合は、URLを該当のエンドポイントに差し替えるだけで手順は同じです。

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

Buildkiteもclaude.com/connectorsのディレクトリには掲載されていないため、カスタムコネクタとしての接続になります。個人のPro・Maxプランでは「Customize > Connectors」→「+」→「Add custom connector」でURLにhttps://mcp.buildkite.com/mcpを入力します。Team・Enterpriseプランでは、Ownerが先に「Organization settings > Connectors」で組織へ追加し、メンバーが個別に接続します。リモート接続はこのConnectors画面のUIのみが案内されており、設定ファイルを直接編集する手順ではありません。

ローカルMCPサーバーをDockerで動かす

自動化ワークフローや、実行するバージョンを固定したい場合はローカルMCPサーバーを使います。BuildkiteはDockerでの実行を推奨しており、イメージはcgr.dev/chainguard/staticをベースにした非特権ユーザー実行のコンテナです。root権限を持たないユーザーでプロセスが動くため、コンテナが侵害されてもホスト側への影響を抑えられます。

docker pull buildkite/mcp-server
docker run --pull=always -q -it --rm \
  -e BUILDKITE_API_TOKEN=<api-token-value> \
  buildkite/mcp-server stdio

Claude Codeからこのローカルサーバーに繋ぐ場合は、Docker実行かバイナリ実行かで登録コマンドが変わります。

claude mcp add buildkite -- docker run --pull=always -q --rm -i \
  -e BUILDKITE_API_TOKEN=bkua_xxxxx buildkite/mcp-server stdio

事前にビルド済みバイナリをインストール済みなら、次のように直接起動できます。

claude mcp add buildkite --env BUILDKITE_API_TOKEN=bkua_xxxxx -- buildkite-mcp-server stdio

APIアクセストークンはBuildkite組織の設定画面から発行します。ローカル型はこのトークンをプレーンテキストで保持することになるため、漏えい対策とアップグレード作業は自分の責任になる点がリモート型との一番の違いです。

Buildkite MCPで何ができるか

BuildkiteのMCPサーバーはREST APIをラップする形で、パイプライン・ビルド・ジョブ・エージェント・クラスタ・アーティファクトを一通りカバーします。主なツールカテゴリは次のとおりです。

カテゴリ代表ツールできること
パイプライン代表ツールlist_pipelines / get_pipelineできること一覧取得、設定・ステップ・ビルド統計の確認
ビルド代表ツールlist_builds / create_build / cancel_build / rebuild_buildできること実行の一覧・新規作成・キャンセル・再実行
ジョブ代表ツールlist_jobs / retry_job / unblock_jobできることジョブの状態確認、再試行、ブロック解除
ログ代表ツールsearch_logs / tail_logs / read_logsできること正規表現検索・末尾表示・行番号指定読み取り
クラスタ代表ツールlist_clusters / list_cluster_queuesできることセルフホストエージェントのキュー管理
Test Engine代表ツールlist_tests / get_failed_executionsできることテストの実行履歴と失敗の詳細を取得
アノテーション代表ツールlist_annotations / create_annotationできることビルド結果への注釈の閲覧・追加

ログ関連のツールは、Buildkiteの複雑なログ形式をParquetファイルに変換してから提供する専用ライブラリを使っており、これによりAIアシスタントが大量のログをそのまま渡されるより効率よく検索・要約できます。変換後のログはキャッシュされるため、同じログに対する2回目以降の検索は高速です。

Test EngineのツールはCIで実行したテストの履歴を扱い、フレーキーな失敗の傾向をClaudeに追わせるのに向いています。アノテーションのツールはビルド結果の画面に表示される注釈を読み書きするもので、カバレッジレポートの要約などを自動で書き込ませる用途に使われます。どちらもデバッグ用のツールセット(tests・annotations)に含まれているため、前述の「デバッグ・障害調査」構成を選べば追加設定なしで使えます。

ツールセットで権限を絞る

Buildkite MCPサーバーはツールをpipelines・builds・logs・clusters・artifacts・testsなどのツールセット単位でまとめており、必要なものだけを有効化できます。ビルドの調査しかさせないならbuildsだけを許可し、パイプラインの作成や更新のような書き込み権限をClaudeに渡さずに済みます。

単一のツールセットに絞るだけなら、リモートMCPサーバーのURLに/x/{toolset名}を追記するだけです。

claude mcp add --transport http buildkite-builds https://mcp.buildkite.com/mcp/x/builds

さらに書き込みを禁止して読み取り専用にしたい場合は、末尾に/readonlyを足します(https://mcp.buildkite.com/mcp/x/builds/readonly)。複数のツールセットを組み合わせたいときは、URLではなくX-Buildkite-Toolsetsヘッダーにカンマ区切りで指定します。何も指定しなければBuildkite API全体にアクセスできる状態になるため、共有環境で使うコネクタほどこの絞り込みの効果が大きくなります。

用途別の組み合わせ例です。どの構成でもuserツールセットは基本情報を返すため含めておきます。

用途組み合わせ
CI/CD管理組み合わせuser + pipelines + builds
デバッグ・障害調査組み合わせuser + builds + logs + tests + annotations
全権限組み合わせツールセットを指定せず素のURLをそのまま使う

CLAUDE.mdにヒントを書いてClaudeの精度を上げる

BuildkiteはAIツール向けの指示ファイル(AGENTS.md、Claude CodeではCLAUDE.md)に、組織名とパイプラインslugのヒントを書いておくことを勧めています。ツール自体は繋がっていても、どの組織のどのパイプラインを指すのかをClaudeが推測しなければならない状態だと、質問のたびにその確認が挟まります。

- **CI/CD**: `my-buildkite-organization` Buildkiteオーガニゼーション、build/testは`my-pipeline`パイプラインslug(`.buildkite/pipeline.yml`)、リリースは`my-pipeline-release`パイプラインslug(`.buildkite/pipeline.release.yml`)

自分の組織名・パイプラインslug・設定ファイル名に置き換えて、CLAUDE.mdの既存のアーキテクチャ節などに1行加えるだけで、以後の質問で毎回組織やパイプラインを指定し直す手間が減ります。

よくあるつまずき

リモート型のOAuthアクセストークンは有効期限が12時間、リフレッシュトークンは7日間です。長時間放置したセッションで急に認証エラーが出たら、まず期限切れを疑って再認証します。

ローカル型は組織の標準REST APIレート制限をそのまま消費しますが、リモート型はユーザーごとに1分あたり50リクエストという専用の別枠(組織のREST APIレート制限とは独立)を持ちます。上限を超えると429エラーが返り、レスポンスのRateLimit-Resetヘッダーで次のウィンドウまでの残り秒数がわかります。この値は日時ではなく秒数そのものなので、自動リトライを組む場合は固定の待機時間を決め打ちせず、ヘッダーの値をそのままスリープ秒数として使えば無駄待ちを減らせます。60秒経てば自動的に回復するので、連続で大量の調査を投げたときにエラーが出ても待てば解消します。

読み取り専用のリモートMCPサーバーでは、スコープがread_で始まらないツール(ビルドの作成やジョブの再試行など書き込み系)は呼び出せません。「再実行して」と頼んでも失敗するのは、権限不足であって設定ミスではないことが多いので、まず接続しているエンドポイントを確認します。読み取り専用にするつもりが通常のURLのまま設定していた、という取り違えもよく起きます。

まとめ

対話的に使うならリモートMCPサーバー、パイプラインからの自動実行や特定バージョン固定が必要ならDockerのローカルMCPサーバーを選びます。認証情報の管理責任がどちらにあるかがこの選択の分かれ目です。同じ非特権コンテナでの運用はKubernetes MCPサーバーにも通じる考え方で、IaC寄りの構成管理まで任せたい場合はTerraform MCPサーバーも参考になります。カスタムコネクタの権限設定でつまずきやすい点はClaude Connectorsの権限設定でよくある失敗にまとめています。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →