Claude Media
ClaudeとJenkinsを連携しビルド失敗を自動診断する
Claude CodeMCPClaude連携チュートリアル

ClaudeとJenkinsを連携しビルド失敗を自動診断する

Jenkins公式のMCP Server Pluginを使うと、Jenkins自体がMCPサーバーになります。ビルドログの検索から変更履歴の突合、Pipelineのreplayまでの診断手順と接続設定をまとめます。

読了目安 約10分

Jenkinsの公式プラグイン「MCP Server Plugin」は、他社のCIツール向けMCPサーバーとは作りが違います。別プロセスとしてサーバーを立てるのではなく、Jenkinsインスタンス自体がプラグインとしてMCPサーバーになる構成です。インストールすればJenkinsのURL配下にMCPエンドポイントが生えるので、ジョブの一覧やビルドログの検索、失敗したPipelineのreplayまで、Claude Codeから自然文で頼めるようになります。

Jenkins自体がMCPサーバーになる仕組み

jenkinsci/mcp-server-pluginはJenkinsプラグインの公式ホスト先orgで配布されており、直近も数日おきに更新が入っている活発なプラグインです。MCP Java SDK 0.17.2をベースに、MCP仕様2025-06-18を実装しています。

インストール後の追加設定は基本的に不要で、3種類のトランスポートエンドポイントが既定で同時に有効になります。

トランスポートエンドポイント向いている場面
Streamable HTTPエンドポイント/mcp-server/mcp向いている場面通常の用途全般。接続の安定性が高く公式の推奨
SSEエンドポイント/mcp-server/sse向いている場面クライアントがSSEしか対応していない場合のみ
Statelessエンドポイント/mcp-server/stateless向いている場面セッション管理なしで独立したリクエストを送るクライアント向け

公式が明示的に推奨しているのはStreamable HTTPです。SSEは長時間張りっぱなしの接続を前提にするため、リバースプロキシやロードバランサーのアイドルタイムアウトに弱く、後述する追加設定が要ります。

Claude Codeから接続する

認証はJenkins本体と同じ仕組みを使います。Jenkinsのユーザーアイコン→Security→Add new tokenでAPIトークンを発行し、ユーザー名:トークンをBase64エンコードしてBasic認証ヘッダーに使います。

echo -n "<username>:<token>" | base64

出力された文字列を使い、Claude Codeに登録します。

claude mcp add jenkins http://jenkins-host/mcp-server/mcp --transport http --header "Authorization: Basic <user:token base64>"

これだけでJenkinsのジョブ・ビルド・SCM情報にアクセスできる状態になります。トークンは一度しか表示されないため、発行直後に安全な場所へ控えておく必要があります。

ビルド失敗を診断する典型的な流れ

プラグインが提供するツールは4つのカテゴリに分かれます。

  • ジョブ管理: getJob(フォルダ配下のジョブはfull pathで指定)/ getJobs(ページング付き一覧)/ triggerBuild(パラメータ付きビルドの実行)/ getQueueItem
  • ビルド情報: getBuild / updateBuild / getBuildLog / searchBuildLog / rebuildBuild / getReplayScripts / replayBuild / getTestResults
  • SCM連携: getJobScm / getBuildScm / getBuildChangeSets / findJobsWithScmUrl
  • 管理情報: whoAmI / getStatus

ビルド失敗を自動診断させるときの基本形はこうなります。

my-jobの直近のビルドが失敗している。ログを調べて原因を教えて。関連する変更点も見せて

ClaudeはまずgetBuildで最新ビルドのステータスを確認し、失敗していればsearchBuildLogでエラーキーワードやスタックトレースのパターンを正規表現検索します。ビルドが実行中でも非ブロッキングでログのスナップショットを読むため、進行中のビルドに対しても即座に応答が返ります。原因の手がかりが掴めたらgetBuildChangeSetsで直近のコミット差分を取得し、「どのコミットが持ち込んだ変更か」まで一緒に提示できます。テストが原因の失敗であればgetTestResultsで失敗したテストケースを直接確認できます。

getBuildLogは大きなログでもページングとカーソル(nextCursor)で読み進められる設計です。末尾から遡って読む「end-relative」読み取りにも対応しており、大量のログの先頭から順に読ませて時間を浪費する事態を避けられます。

パラメータ付きビルドの実行とPipelineのreplay

triggerBuildはパラメータ付きジョブに対応しています。

{
  "jobFullName": "my-parameterized-job",
  "parameters": {
    "BRANCH": "main",
    "DEBUG_MODE": true
  }
}

Stringやbooleanなどのコアパラメータ型はそのまま渡せ、プラグインが追加するカスタムパラメータ型もリフレクションで自動検出されます。対応していないパラメータは既定値にフォールバックし、ログに記録される仕組みです。

Pipelineジョブで原因の仮説を立てたら、実際にJenkinsfileを書き換えてpushする前にgetReplayScriptsでスクリプトを取得し、replayBuildに修正版のスクリプトを渡して試すことができます。Replay機能が有効なジョブであれば、コミットせずに1回だけ挙動を確認できるため、原因調査と本修正のコミットを分けて進められます。

SCM情報でジョブを横断的に探す

原因調査がコード側に及ぶ場合、SCM連携のツールが役立ちます。getJobScmとgetBuildScmはジョブ・ビルドそれぞれに紐づくリポジトリ設定を返し、getBuildChangeSetsは該当ビルドに含まれるコミットの変更ログを返します。地味に使えるのがfindJobsWithScmUrlで、特定のGitリポジトリURLを指定すると、そのリポジトリをビルドしているジョブを横断的に洗い出せます。「このリポジトリを触ったら、他にどのジョブが動くか」を事前に把握したいときに向いています。

git@github.com:myorg/shared-lib.gitを使っているJenkinsジョブを全部教えて

接続状態を監視する

MCP接続自体の健全性を確認する専用エンドポイントが2つ用意されています。<jenkins-url>/mcp-healthは認証不要の軽量エンドポイントで、サーバーの稼働状況とアクティブな接続数を即座に返します。CIのヘルスチェックやダッシュボードから10〜30秒間隔でポーリングし、503が返り始めたら再接続に備える、という使い方が想定されています。Jenkinsのシャットダウン時にはこのエンドポイントが猶予期間つきで503を返すため、クライアント側はRetry-Afterヘッダーを見て再接続のタイミングを計れます。

もう1つの<jenkins-url>/mcp-server/metricsはJenkinsの標準権限が必要な認証付きエンドポイントで、SSE接続の累計・現在アクティブ数、Streamable HTTPのリクエスト累計、接続エラー数、稼働時間を返します。MCP接続がチーム全体でどれだけ使われているかを把握したい場合に参照します。

独自ツールを追加する

McpServerExtensionインターフェースを実装したクラスを作り、メソッドに@Toolアノテーションを付ければ、Jenkinsプラグイン開発者は組織固有のツールを追加できます。既存の組み込みツールと同じ名前を付けてoverride = trueを指定すれば、getBuildLogのような標準ツールを自社仕様の実装で置き換えることも可能です。名前が衝突していてoverrideを指定していない場合は、標準ツールが優先されログに警告が出るだけなので、意図しない上書きは起こりません。社内向けのJenkinsプラグインを持つ組織であれば、既存の拡張ポイントにMCPツールを足す形で自然に統合できます。

ツールの戻り値はどう整形されるか

getJobsのような一覧系ツールは、返ってきたリストの各要素が個別のテキストコンテンツとして展開されます。getJobのような単一オブジェクト系ツールは、オブジェクト全体が1つのテキストコンテンツにまとまります。シリアライズには2種類の経路があり、Jenkins標準の@ExportedBeanが付いたオブジェクトはJenkins自体のJSONエクスポート機構を、それ以外は通常のJacksonによるJSONシリアライズを使います。実装の違いを意識する場面は多くありませんが、カスタムツールを自作する側にとっては、既存のJenkinsオブジェクトをそのまま返せばこの変換を自前で書かずに済むという利点になります。

よくあるつまずき

  • SSE接続がすぐ切れる: JenkinsはWinstone(組み込みJetty)のhttpKeepAliveTimeoutが既定30秒で、MCPのkeep-alive ping間隔(既定30秒)と競合し、pingが届く前に接続が閉じられることがあります。起動オプションに--httpKeepAliveTimeout=600000を追加するか、そもそもStreamable HTTPに切り替えれば影響を受けません
  • リバースプロキシ経由でタイムアウトする: Nginxなどのプロキシでproxy_read_timeoutが短いと、triggerBuildのような時間のかかるツール呼び出しが504 Gateway Timeoutで終わることがあります。これはトランスポートを問わず起こるため、proxy_read_timeoutを600秒程度に伸ばしておきます
  • Originヘッダーが必須だと思い込む: MCP仕様はOriginヘッダーの検証を要求していますが、本プラグインは既定でヘッダーが無いリクエストも許可します(requireOriginHeader=false)。ヘッダー自体を必須にしたい場合だけシステムプロパティを明示的に変更します
  • Copilotでストリーミングが不安定: プラグインのドキュメントはCopilot使用時、Streamable HTTPよりSSEエンドポイントの利用を勧めています。クライアントによって相性が異なる点はこのプラグインに限った話ではなく、まず公式が推すStreamable HTTPを試し、うまくいかない場合だけSSEに切り替えるのが安全です
  • 接続はできるがツール呼び出しが全部失敗する: 認証ヘッダー自体は通っていても、Basic認証の文字列に含めたトークンの権限が不足しているケースがあります。まずwhoAmIを呼んで自分がどのユーザーとして認識されているかを確認し、getStatusでJenkinsインスタンス自体の健全性を切り分けます

まとめ

Jenkins MCP Server Pluginは、Jenkins本体にプラグインとして追加するだけでビルド・ジョブ・SCM情報を丸ごとMCPツールに変換します。ビルド失敗の一次診断はgetBuild→searchBuildLog→getBuildChangeSets→getTestResultsという流れで完結し、仮説が立てばreplayBuildでコミット前に修正を試せます。認証はJenkins本体のAPIトークンをそのまま使うため、Jenkins側で新しいアカウントや権限体系を別途用意する必要がない点も導入のハードルを下げています。

MCPサーバーの追加構文や--headerオプションの詳細はClaude Code MCP設定ガイドにまとめています。MCPのHost/Client/Serverという基本構造はMCPアーキテクチャの三層構造にまとめています。

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

関連する記事

Claude Code をもっと見る →