jaeger-mcp

jaeger-mcp

Jaeger 分散トレーシング向けの MCP サーバーです。 Claude（または MCP 対応のエージェント）にトレースデータへの読み取りアクセスを提供します。会話を離れることなく、トレースの検索、スパンの調査、トレースの比較、スパン統計の計算、サービス依存関係のマッピング、パフォーマンス問題の予測、キャパシティ需要の予測を行えます。

Jaeger MCP がもう一つ必要なのはなぜですか？

既存の Jaeger インテグレーションでは、実行中の UI またはカスタムスクリプトが必要です。このサーバーには次の特長があります。

• 標準の Model Context Protocol を stdio 経由で使用するため、Claude Desktop、Claude Code、Cursor、およびあらゆる MCP クライアントで動作します。
• 読み取り専用です。15 個すべてのツールに readOnlyHint: true が設定されており、トレースデータを変更するリスクはありません。
• デュアルチャネル出力を返します。プログラムでの利用向けの構造化 JSON（structuredContent）と、人が読みやすい表示向けの Markdown（content）を提供します。
• 修正すべき正確な環境変数を示し、次のステップを提案する、実行可能なエラーメッセージを備えています。
• Bearer トークン、HTTP Basic 認証、または認証なし（内部デプロイで一般的）に対応しています。
• 基盤となる Jaeger Query API を記載した OpenAPI 仕様（openapi.yaml）が含まれています。

ツール

ツール	エンドポイント	説明
jaeger_list_services	GET /api/services	インストルメント化されたすべてのサービスを一覧表示
jaeger_list_operations	GET /api/services/{service}/operations	サービスのオペレーション名を一覧表示
jaeger_search_traces	GET /api/traces	詳細なフィルターでトレースを検索
jaeger_get_trace	GET /api/traces/{traceID}	スパンツリーを含むトレースの全詳細
jaeger_get_dependencies	GET /api/dependencies	サービス間の呼び出しグラフ
jaeger_compare_traces	GET /api/traces/{traceID} ×2	2 つのトレース間の構造的な差分
jaeger_span_statistics	GET /api/traces	オペレーションごとのレイテンシとエラーの統計
jaeger_critical_path	GET /api/traces/{traceID}	所要時間が最長のスパンチェーンとボトルネックのランキング
jaeger_compare_windows	GET /api/traces ×2	2 つの期間におけるトレース動作の集計比較
jaeger_detect_anomalies	GET /api/traces ×2	オペレーションごとのレイテンシ／エラー率の急上昇を統計的に検出
jaeger_predict_degradation	GET /api/traces	2～24 時間先のパフォーマンス低下を予測
jaeger_forecast_capacity	GET /api/traces	スループット需要と必要なリソースを予測
jaeger_find_test_traces	GET /api/traces	タグクエリ（Allure/pytest/カスタム）でテスト実行とそのトレースを関連付け
jaeger_regression_diff	GET /api/traces ×2	2 つの時間枠におけるオペレーションごとのリグレッションを分類
jaeger_test_profile	GET /api/traces	タグ付けされたテスト実行のオペレーションごとのレイテンシホットスポット

インストール

pip install jaeger-mcp

または、インストールせずに直接実行できます。

uvx jaeger-mcp

設定

すべての設定は環境変数で行います。

変数	必須	デフォルト	説明
JAEGER_URL	はい	—	Jaeger クエリサービスの URL（例：https://jaeger.example.com）
JAEGER_TOKEN	いいえ	—	Bearer トークン（Basic 認証より優先されます）
JAEGER_USERNAME	いいえ	—	HTTP Basic 認証のユーザー名
JAEGER_PASSWORD	いいえ	—	HTTP Basic 認証のパスワード
JAEGER_SSL_VERIFY	いいえ	true	自己署名証明書の場合は false に設定します
JAEGER_TIMEOUT	いいえ	30	HTTP リクエストのタイムアウト（秒）
JAEGER_RETRY_ATTEMPTS	いいえ	3	一時的な障害時の再試行回数（無効にする場合は 0）
JAEGER_CACHE_TTL	いいえ	120	検出エンドポイントのキャッシュ TTL（秒、無効にする場合は 0）

.env.example を .env にコピーし、値を入力してください。

Claude Desktop / Claude Code の設定

MCP 設定（claude_desktop_config.json または .claude/mcp.json）に追加します。

{
  "mcpServers": {
    "jaeger": {
      "command": "jaeger-mcp",
      "env": {
        "JAEGER_URL": "https://jaeger.example.com",
        "JAEGER_TOKEN": "your-token-here"
      }
    }
  }
}

または uvx を使用します（インストール不要）。

{
  "mcpServers": {
    "jaeger": {
      "command": "uvx",
      "args": ["jaeger-mcp"],
      "env": {
        "JAEGER_URL": "https://jaeger.example.com"
      }
    }
  }
}

Docker

docker run --rm -e JAEGER_URL=https://jaeger.example.com jaeger-mcp

クエリの例

設定が完了したら、Claude に次のように質問してください。

• 「Jaeger が把握しているサービスを教えてください」
• 「過去 1 時間に order-service で発生した HTTP 500 エラーを含むトレースを検索してください」
• 「GET /checkout の最も遅いトレース（2 秒超）を表示してください」
• 「トレース abcdef1234567890 のエラーの原因は何ですか？」
• 「過去 7 日間のサービス依存関係グラフを作成してください」
• 「postgres を最も頻繁に呼び出しているサービスはどれですか？」
• 「トレース abc123 とトレース def456 を比較してください。どのスパンが変わりましたか？」
• 「order-service の操作ごとの p95 レイテンシを教えてください」

ツールの使い方ガイド

jaeger_list_services

Jaeger が確認したサービス名をすべて返します。計測されているサービスがわからない場合は、ここから始めてください。出力は最大 500 サービスに制限され、切り捨てられた場合はその旨が表示されます。

jaeger_list_operations

指定したサービスの操作名（HTTP ルート名や gRPC メソッド名など）をすべて返します。jaeger_search_traces で絞り込む前に、使用可能な操作名を確認するために使います。

jaeger_search_traces

メインの検索ツールです。次の条件で絞り込みます。

• service（必須）— jaeger_list_services で確認したサービス名
• operation — 特定のエンドポイントに絞り込みます
• tags — タグフィルターを指定する JSON 文字列（例：{"http.status_code":"500"} または {"error":"true"}）
• start / end — UTC の時間範囲（マイクロ秒）
• min_duration / max_duration — "100ms"、"1.5s"、"2m" のような期間文字列
• limit — デフォルトは 20、最大は 1500

trace_id、duration_us、span_count、service_count、root_operation、errors_count を含むトレースの概要を返します。

jaeger_get_trace

トレースの詳細をすべて返します。trace_id（16～32 文字の 16 進文字列）を受け取り、次の情報を返します。

• タグ、サービス名、親子関係を含むすべてのスパン
• サービスごとの統計情報（スパン数、合計時間、エラー数）
• 実行ツリー（各ノードに子スパンの ID を表示）

エラースパンは tags["error"] = "true" で識別されます。

jaeger_get_dependencies

サービスのトポロジーグラフを返します。call_count を含む有向エッジ (parent → child) が返されます。lookback_hours（デフォルトは 24、最大は 720）を使って対象期間を指定します。

jaeger_compare_traces

2 つのトレース間の構造上の差分を返します。2 つの trace_id の 16 進文字列を受け取り、スパン ID ではなく (operationName, serviceName, parentOperation) でスパンを照合します。次の情報を報告します。

• 追加されたスパン — トレース B には存在し、トレース A には存在しないスパン
• 削除されたスパン — トレース A には存在し、トレース B には存在しないスパン
• 変更されたスパン — 照合されたものの、期間またはタグが異なるスパン（差分を表示）
• 変更のない数 — 同一のスパン数

遅いトレースと速いトレースの比較や、デプロイ間の変更点の確認に使います。

jaeger_span_statistics

操作ごとのレイテンシパーセンタイルとエラー率です。サービスのトレースを最大limit件（デフォルトは20件、最大100件）取得し、すべてのスパンを操作名ごとに集計します。操作ごとに次の情報を報告します。

• count — 観測されたスパンの総数
• p50_duration_us、p95_duration_us、p99_duration_us — レイテンシパーセンタイル
• error_count、error_rate — エラー（tags["error"] = "true"で識別）

サービス内で最も遅い操作や、エラーが最も発生しやすい操作を見つけるために使用します。

jaeger_critical_path

トレース内でルートからリーフまで続く、最も所要時間の長いスパンチェーン（クリティカルパス）を特定し、自己時間でスパンを順位付けしてパフォーマンスのボトルネックを見つけます。

次の情報を報告します。

• 操作、サービス、所要時間、全体に占める割合を含むクリティカルパスのスパン
• 排他的所要時間（自己時間）で順位付けされたボトルネックのスパン

「このトレースはなぜこんなに遅いのか？」や「CPU／自己時間を最も消費している操作はどれか？」という問いに答えるために使用します。

jaeger_compare_windows

サービスの2つの期間におけるトレースの集計動作を比較し、デプロイ間のパフォーマンスの低下や改善を検出します。

次の情報を報告します。

• 追加、削除、高速化、低速化した操作を示す、操作ごとの差分の概要
• 操作ごとおよび全体の数値スコアによる偏差スコア
• レイテンシパーセンタイル（p50、p95）の変化とエラー率の差分

「最新のデプロイはパフォーマンスに影響したか？」や「データベースのアップグレード後に遅くなった操作はどれか？」という問いに答えるために使用します。

jaeger_detect_anomalies

サービスの最近のトレースを過去のベースラインと比較し、統計的に有意なレイテンシの急増やエラー率の上昇がないか調べます。

次の情報を報告します。

• 異常の種類（latencyまたはerror_rate）と、フラグが付けられた操作
• zスコアを伴う重大度の分類（低から重大）
• 影響を受けた指標の現在値とベースライン値

ユーザーに影響が及ぶ前に、パフォーマンスの低下や信頼性の問題を予防的に特定するために使用します。

ライブラリファサード（プロセス内での使用）

jaeger-mcpは、MCP サーバーを使わずにPythonライブラリとしても使用できます。

from jaeger_mcp import JaegerClient

client = JaegerClient.from_env()  # reads JAEGER_URL from env
trace = client.get_trace("abcdef1234567890abcdef1234567890")

for span in trace.spans:
    if span.error:
        print(f"{span.service_name}: {span.operation} at {span.start_utc}")
        print(f"  tags: {span.tags}")

利用可能なメソッド：get_trace()、search_traces()、list_services()、get_dependencies()、compare_traces()、span_statistics()、critical_path()、compare_windows()、detect_anomalies()、predict_degradation()、forecast_capacity()、find_test_traces()、regression_diff()、test_profile()。

ドメインオブジェクト：Span、Trace、TraceSummary、ServiceDep、TraceComparison、SpanIdentity、SpanChange、SpanStatisticsResult、OperationStatResult、CriticalPathOutput、CriticalPathSpan、BottleneckSpan、WindowComparisonOutput、OperationDiff、AnomalyDetectionOutput、OperationAnomaly — すべて型付きフィールドを備えています。

APIドキュメント

このプロジェクトには、docs/ディレクトリに包括的なOpenAPI仕様が含まれています。

1. Jaeger Query Service API（openapi.yaml） — Jaegerの実際のAPIエンドポイントを記述します
2. MCP Tools API（docs/mcp-tools-openapi.yaml） — MCPツールを概念上のHTTPエンドポイントとして記述します

これらの仕様は、次の用途に役立ちます。

• 各ツールが行う基盤API呼び出しの理解
• 代替インテグレーションの開発
• API連携のデバッグ
• クライアントライブラリやドキュメントの生成

両方の仕様の詳細については、docs/README.mdを参照してください。

パフォーマンス特性

• すべてのツールで、コネクションプーリングを使用する単一の永続的な requests.Session を使用します。
• Jaeger は通常内部サービスであるため、セッションの trust_env = False に設定して環境プロキシをバイパスします。
• リクエストは 30 秒でタイムアウトします（JAEGER_TIMEOUT で設定可能）。
• 一時的な HTTP エラー（429/5xx）は、指数バックオフで再試行されます（JAEGER_RETRY_ATTEMPTS で設定可能）。
• list_services と list_operations のレスポンスは 120 秒間キャッシュされます（JAEGER_CACHE_TTL で設定可能）。
• jaeger_search_traces は limit を Jaeger にそのまま渡します。必要以上のトレースをリクエストしないでください。
• jaeger_get_trace は 1 回の呼び出しでトレース全体を取得します。大規模なトレース（数千のスパン）は時間がかかる場合があります。
• jaeger_get_dependencies は全ルックバック期間にわたって集計します。大規模なクラスターでは、期間が長いと処理に時間がかかる場合があります。

開発

git clone https://github.com/mshegolev/jaeger-mcp
cd jaeger-mcp
pip install -e '.[dev]'
pytest tests/ -v
ruff check src tests
ruff format src tests

ライセンス

MIT — LICENSE を参照してください。