Jenkins MCP Server

🚀 Jenkins MCP Server

Jenkins MCP Serverは、Jenkins CI/CDとのシームレスな統合を可能にするエンタープライズグレードのMCP（Model Context Protocol）サーバーです。ClaudeなどのAIアシスタントが、包括的で本番環境に対応したAPIを通じてJenkinsとやり取りできるようになります。

🚀 クイックスタート

npmによるインストール（推奨）

# グローバルインストール
npm install -g @ashwinighuge/jenkins-mcp-server

# またはnpxで直接使用
npx @ashwinighuge/jenkins-mcp-server --help

Claude Desktopとの統合

claude_desktop_config.jsonに以下を追加します。

{
  "mcpServers": {
    "jenkins": {
      "command": "jenkins-mcp",
      "env": {
        "JENKINS_URL": "http://your-jenkins-server:8080",
        "JENKINS_USER": "your-username",
        "JENKINS_API_TOKEN": "your-api-token"
      }
    }
  }
}

✨ 主な機能

• 🔧 ジョブ管理：フルフォルダサポート付きで、Jenkinsジョブのトリガー、一覧表示、検索、モニタリングが可能
• 📊 ビルドステータス：リアルタイムのビルドステータス追跡とコンソールログのストリーミング
• 🔄 パイプラインサポート：詳細なログ付きで段階的なパイプライン実行のモニタリング
• 📦 アーティファクト管理：複数のビルドにまたがるビルドアーティファクトの一覧表示、ダウンロード、検索
• ⚡ バッチ操作：インテリジェントな優先度キューイングによる並列ジョブ実行
• 🚀 パフォーマンスキャッシュ：自動無効化機能付きの多層インテリジェントキャッシュシステム
• 🔍 高度なフィルタリング：正規表現サポート付きで、ステータス、結果、日付などでジョブをフィルタリング
• 📋 キュー管理：リアルタイムのビルドキューのモニタリングと管理
• 🔒 エンタープライズセキュリティ：CSRF保護、2FAサポート、および安全な認証
• 🌐 クロスプラットフォーム：Windows、macOS、Linuxで動作
• 🔄 リトライロジック：信頼性向上のための組み込み指数バックオフ
• 📡 トランスポートの柔軟性：STDIOとHTTPの両方のトランスポートをサポート
• ✅ 入力検証：堅牢なPydanticベースの検証とエラーハンドリング

📋 前提条件

• Node.js：14.0.0以上
• Python：3.12以上
• Jenkins：2.401+（推奨）
• Jenkins APIトークン：認証用

🛠 インストール方法

方法1: npm（推奨）

# システム全体でアクセスできるようにグローバルインストール
npm install -g @ashwinighuge/jenkins-mcp-server

# インストールの確認
jenkins-mcp --help

方法2: 開発環境のセットアップ

# リポジトリをクローン
git clone https://github.com/AshwiniGhuge3012/jenkins-mcp-server
cd jenkins-mcp-server

# Node.jsの依存関係をインストール
npm install

# Pythonの依存関係をインストール
pip install -r requirements.txt  # またはuv pip installを使用

# ローカルで実行
node bin/jenkins-mcp.js --help

🔐 設定

環境変数

作業ディレクトリに.envファイルを作成します。

# 必須のJenkins設定
JENKINS_URL="http://your-jenkins-server:8080"
JENKINS_USER="your-username"
JENKINS_API_TOKEN="your-api-token"

# オプション: サーバー設定
MCP_PORT=8010
MCP_HOST=0.0.0.0

# オプション: リトライ設定
JENKINS_MAX_RETRIES=3
JENKINS_RETRY_BASE_DELAY=1.0
JENKINS_RETRY_MAX_DELAY=60.0
JENKINS_RETRY_BACKOFF_MULTIPLIER=2.0

# オプション: パフォーマンスキャッシュ設定
JENKINS_CACHE_STATIC_TTL=3600        # 1時間
JENKINS_CACHE_SEMI_STATIC_TTL=300    # 5分
JENKINS_CACHE_DYNAMIC_TTL=30         # 30秒
JENKINS_CACHE_SHORT_TTL=10           # 10秒
JENKINS_CACHE_STATIC_SIZE=1000       # 最大キャッシュアイテム数
JENKINS_CACHE_SEMI_STATIC_SIZE=500
JENKINS_CACHE_DYNAMIC_SIZE=200
JENKINS_CACHE_PERMANENT_SIZE=2000
JENKINS_CACHE_SHORT_SIZE=100

Jenkins APIトークンの取得方法

1. Jenkinsインスタンスにログインします。
2. ユーザー名をクリックし、Configureを選択します。
3. API Tokenセクションまでスクロールします。
4. Add new Tokenをクリックします。
5. トークンに名前を付け、Generateをクリックします。
6. 生成されたトークンをコピーし（安全に保存してください！）ます。

🚀 使用方法

コマンドラインインターフェイス

# STDIOモード（デフォルト、Claude Desktop用）
jenkins-mcp

# HTTPモード（MCP Gateway用）
jenkins-mcp --transport streamable-http --port 8010

# カスタムホストとポート
jenkins-mcp --transport streamable-http --host localhost --port 9000

# ヘルプを表示
jenkins-mcp --help

トランスポートモード

高度な使用例

# npxで使用（グローバルインストール不要）
npx @ashwinighuge/jenkins-mcp-server

# 環境変数を使用
JENKINS_URL=http://localhost:8080 JENKINS_USER=admin JENKINS_API_TOKEN=abc123 jenkins-mcp

# カスタム設定でHTTPモード
jenkins-mcp --transport streamable-http --host 0.0.0.0 --port 8080

利用可能なツール

このMCPサーバーが公開するツールのリストです。

trigger_job

• 説明：オプションのパラメーターを指定してJenkinsジョブをトリガーします。
• パラメーター：
  • job_name (文字列)：Jenkinsジョブの名前。
  • params (オブジェクト、オプション)：ジョブパラメーターをJSONオブジェクトとして指定します。マルチセレクトパラメーターの場合は、文字列の配列を渡します。
• 戻り値：キューURLを含む確認メッセージ。

get_job_info

• 説明：Jenkinsジョブの詳細情報（パラメーターを含む）を取得します。
• パラメーター：
  • job_name (文字列)：Jenkinsジョブの名前。
• 戻り値：ジョブの説明、パラメーター、および最後のビルド番号を含むオブジェクト。

get_build_status

• 説明：特定のビルドのステータスを取得します。
• パラメーター：
  • job_name (文字列)：Jenkinsジョブの名前。
  • build_number (整数)：ビルド番号。
• 戻り値：ビルドステータス、タイムスタンプ、期間、およびURLを含むオブジェクト。

get_console_log

• 説明：特定のビルドのコンソールログを取得します。
• パラメーター：
  • job_name (文字列)：Jenkinsジョブの名前。
  • build_number (整数)：ビルド番号。
  • start (整数、オプション)：ログを取得する開始バイト位置。
• 戻り値：コンソールログのテキストと、さらにデータが利用可能かどうかの情報。

list_jobs

• 説明：高度なフィルタリング機能を使って、Jenkinsサーバー上のすべての利用可能なジョブをリストします。
• パラメーター：
  • recursive (ブール値、オプション)：Trueの場合、フォルダを再帰的にトラバースします（デフォルト: True）
  • max_depth (整数、オプション)：再帰する最大深度（デフォルト: 10）
  • include_folders (ブール値、オプション)：フォルダ項目を含めるかどうか（デフォルト: False）
  • status_filter (文字列、オプション)：ジョブのステータスでフィルタリング："building", "queued", "idle", "disabled"
  • last_build_result (文字列、オプション)：最後のビルド結果でフィルタリング："SUCCESS", "FAILURE", "UNSTABLE", "ABORTED", "NOT_BUILT"
  • days_since_last_build (整数、オプション)：過去N日以内にビルドされたジョブのみ
  • enabled_only (ブール値、オプション)：Trueの場合、有効なジョブのみ；Falseの場合、無効なジョブのみ
• 戻り値：ビルドステータスやタイムスタンプなどの拡張メタデータを含むジョブのリスト。

search_jobs

• 説明：高度なフィルタリングを使ったパターンマッチングでJenkinsジョブを検索します。
• パラメーター：
  • pattern (文字列)：ジョブ名をマッチングするパターン（'build*', 'test'などのワイルドカードをサポート）
  • job_type (文字列、オプション)：タイプでフィルタリング - "job", "folder", または "all"（デフォルト: "job"）
  • max_depth (整数、オプション)：検索する最大深度（デフォルト: 10）
  • use_regex (ブール値、オプション)：Trueの場合、パターンを正規表現として扱います（デフォルト: False）
  • status_filter (文字列、オプション)：ジョブのステータスでフィルタリング："building", "queued", "idle", "disabled"
  • last_build_result (文字列、オプション)：最後のビルド結果でフィルタリング："SUCCESS", "FAILURE", "UNSTABLE", "ABORTED", "NOT_BUILT"
  • days_since_last_build (整数、オプション)：過去N日以内にビルドされたジョブのみ
  • enabled_only (ブール値、オプション)：Trueの場合、有効なジョブのみ；Falseの場合、無効なジョブのみ
• 戻り値：拡張メタデータと完全なパスを含む一致するジョブのリスト。

get_queue_info

• 説明：現在キューにあるビルドの情報を取得します。
• パラメーター：なし
• 戻り値：キュー内のアイテムのリスト。

server_info

• 説明：Jenkinsサーバーの基本情報を取得します。
• パラメーター：なし
• 戻り値：JenkinsのバージョンとURL。

get_pipeline_status

• 説明：Jenkins Pipelineジョブビルドの詳細なパイプラインステージステータスを取得します。
• パラメーター：
  • job_name (文字列)：Jenkins Pipelineジョブの名前。
  • build_number (整数)：ビルド番号。
• 戻り値：段階ごとのステータス、タイミング、期間、およびログを含むパイプライン実行の詳細。

list_build_artifacts

• 説明：特定のJenkinsビルドのすべてのアーティファクトをリストします。
• パラメーター：
  • job_name (文字列)：Jenkinsジョブの名前。
  • build_number (整数)：アーティファクトをリストするビルド番号。
• 戻り値：ファイル名、サイズ、およびダウンロードURLを含むすべてのアーティファクトの情報。

download_build_artifact

• 説明：特定のビルドアーティファクトの内容をダウンロードします（安全性のため、テキストベースのアーティファクトのみ）。
• パラメーター：
  • job_name (文字列)：Jenkinsジョブの名前。
  • build_number (整数)：アーティファクトを含むビルド番号。
  • artifact_path (文字列)：アーティファクトの相対パス（list_build_artifactsから取得）。
  • max_size_mb (整数、オプション)：ダウンロードする最大ファイルサイズ（MB）（デフォルト: 50MB）。
• 戻り値：アーティファクトの内容（テキストファイルの場合）またはダウンロード情報。

search_build_artifacts

• 説明：パターンマッチングを使って、ジョブの最近のビルドにまたがってアーティファクトを検索します。
• パラメーター：
  • job_name (文字列)：検索するJenkinsジョブの名前。
  • pattern (文字列)：アーティファクト名をマッチングするパターン（ワイルドカードまたは正規表現）。
  • max_builds (整数、オプション)：検索する最近のビルドの最大数（デフォルト: 10）。
  • use_regex (ブール値、オプション)：Trueの場合、パターンを正規表現として扱います（デフォルト: False）。
• 戻り値：ビルド間で一致するアーティファクトのリストとそのメタデータ。

batch_trigger_jobs

• 説明：並列実行と優先度キューイングを使って、複数のJenkinsジョブをバッチでトリガーします。
• パラメーター：
  • operations (配列)：ジョブ操作のリストで、それぞれに以下が含まれます。
    • job_name (文字列)：Jenkinsジョブの名前
    • params (オブジェクト、オプション)：ジョブパラメーター
    • priority (整数、オプション)：優先度1 - 10（1 = 最高、デフォルト: 1）
  • max_concurrent (整数、オプション)：同時にトリガーできる最大ジョブ数（デフォルト: 5）
  • fail_fast (ブール値、オプション)：最初の失敗で処理を停止する（デフォルト: false）
  • wait_for_completion (ブール値、オプション)：すべてのジョブが完了するまで待つ（デフォルト: false）
• 戻り値：操作ID、結果、および実行統計を含むバッチ操作の応答。

batch_monitor_jobs

• 説明：バッチ操作とその個々のジョブのステータスを監視します。
• パラメーター：
  • operation_id (文字列)：batch_trigger_jobsから返される操作ID。
• 戻り値：バッチ操作の現在のステータス（進行状況と個々のジョブのステータスを含む）。

batch_cancel_jobs

• 説明：バッチ操作をキャンセルし、必要に応じて実行中のビルドをキャンセルします。
• パラメーター：
  • operation_id (文字列)：キャンセルする操作ID。
  • cancel_running_builds (ブール値、オプション)：実行中のビルドをキャンセルしようとする（デフォルト: false）。
• 戻り値：キャンセルステータスと結果。

get_cache_statistics

• 説明：包括的なキャッシュパフォーマンスメトリクスと利用率統計を取得します。
• パラメーター：なし
• 戻り値：キャッシュのヒット率、利用率のパーセンテージ、およびすべてのキャッシュタイプの詳細な統計。

clear_cache

• 説明：パフォーマンス管理のために、細粒度の制御でキャッシュをクリアします。
• パラメーター：
  • cache_type (文字列、オプション)：クリアするキャッシュのタイプ ('all', 'static', 'semi_static', 'dynamic', 'permanent', 'short')
  • job_name (文字列、オプション)：特定のジョブのキャッシュのみをクリア
• 戻り値：キャッシュクリア操作の確認。

warm_cache

• 説明：パフォーマンス向上のために、頻繁にアクセスされるデータをキャッシュに事前ロードします。
• パラメーター：
  • operations (配列、オプション)：ウォームアップする操作 ('server_info', 'job_list', 'queue_info')
• 戻り値：成功/失敗ステータスを含むキャッシュウォーミング操作の結果。

summarize_build_log

• 説明：（デモンストレーション）事前構成されたLLMプロンプトを使って、ビルドログを要約します。
• パラメーター：
  • job_name (文字列)：Jenkinsジョブの名前。
  • build_number (整数)：ビルド番号。
• 戻り値：プレースホルダーの要約と使用されるプロンプト。

💡 使用例

Claude Desktopとの連携

claude_desktop_config.jsonで設定した後、Claudeに以下のように問いかけることができます。

"すべてのJenkinsジョブをリストして"

"versionパラメーターを1.2.3に設定してdeploy-prodジョブをトリガーして"

"api-testsジョブのビルド#45のコンソールログを表示して"

"過去24時間以内に失敗したすべてのジョブのステータスはどうなっている？"

MCP Gatewayとの連携

# HTTPモードでサーバーを起動
jenkins-mcp --transport streamable-http --port 8010

# 例: API呼び出し（curlを使用）
curl -X POST http://localhost:8010/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {"name": "list_jobs", "arguments": {}}}'

バッチ操作の例

# 異なる優先度で複数のジョブをトリガー
jenkins-mcp # 次にbatch_trigger_jobsツールを以下のように使用
{
  "operations": [
    {"job_name": "unit-tests", "priority": 1},
    {"job_name": "integration-tests", "priority": 2},
    {"job_name": "deploy-staging", "priority": 3}
  ],
  "max_concurrent": 3,
  "wait_for_completion": true
}

🔧 トラブルシューティング

一般的な問題と解決策

Pythonの依存関係の問題

# Pythonパッケージの自動インストールが失敗した場合
pip install mcp[cli] pydantic requests python-dotenv fastapi cachetools

# またはuvを使用（推奨）
uv pip install mcp[cli] pydantic requests python-dotenv fastapi cachetools

権限の問題（Linux/macOS）

# パーミッションが拒否された場合
sudo npm install -g @ashwinighuge/jenkins-mcp-server

# またはユーザーレベルのインストールを使用
npm install -g @ashwinighuge/jenkins-mcp-server --prefix ~/.local

Jenkinsへの接続問題

• JENKINS_URLがアクセス可能かどうかを確認します。
• APIトークンが有効で期限切れでないことを確認します。
• ファイアウォール/プロキシ設定を確認します。
• HTTPSの場合、SSL証明書を検証します。

2FA/CSRFの問題

• サーバーは自動的にCSRFトークンを処理します。
• 2FA環境では、APIトークンを使用してください（パスワードではなく）。
• メールOTPなどの2FA方法がサポートされています。

デバッグモード

# 詳細なログを有効にする
DEBUG=jenkins-mcp jenkins-mcp

# Pythonの依存関係を確認する
jenkins-mcp --help  # 依存関係を検証します

📊 パフォーマンス機能

• 多層キャッシュ：自動無効化機能付きのインテリジェントキャッシュ
• バッチ処理：優先度キューイングを使った並列ジョブ実行
• リトライロジック：ネットワークの信頼性向上のための指数バックオフ
• コネクションプーリング：効率的なHTTPコネクション管理
• メモリ最適化：キャッシュサイズとTTL値を設定可能

🤝 コントリビュートの方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します：git checkout -b feature/amazing-feature
3. 変更をコミットします：git commit -m 'Add amazing feature'
4. ブランチにプッシュします：git push origin feature/amazing-feature
5. プルリクエストを作成します。

📄 ライセンス

このプロジェクトはApache 2.0ライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

🙋‍♂️ サポート

• ドキュメント：GitHub README
• イシュー：GitHub Issues
• npmパッケージ：@ashwinighuge/jenkins-mcp-server

🏗️ アーキテクチャ

以下の技術を使用して構築されています。

• Python 3.12+ - コアサーバーの実装
• FastMCP - MCPプロトコルの処理
• Node.js - クロスプラットフォームのラッパーとプロセス管理
• Pydantic - データ検証とシリアル化
• Requests - リトライロジック付きのHTTPクライアント
• CacheTools - 多層パフォーマンスキャッシュ