jaeger-mcp

Jaeger分散トレーシング用MCPサーバー。 Claude（またはMCP対応エージェント）にトレースデータへの読み取りアクセス権を与え、会話を離れることなくトレースの検索、スパンの調査、サービス依存関係のマッピングを行えます。

なぜ別のJaeger MCPが必要なのか？

既存のJaeger統合では、実行中のUIやカスタムスクリプトが必要でした。このサーバーは以下の特徴があります：

• 標準のModel Context Protocolをstdio経由で話すため、Claude Desktop、Claude Code、Cursor、およびあらゆるMCPクライアントで動作します。

• 読み取り専用：5つのツールすべてにreadOnlyHint: trueが設定されており、トレースデータを変更するリスクはゼロです。

• デュアルチャネル出力：プログラム利用向けの構造化JSON（structuredContent）と、人間が読みやすいMarkdown（content）の両方を返します。

• 実用的なエラーメッセージ：修正すべき環境変数を正確に示し、次のステップを提案します。

• 認証サポート：Bearerトークン、HTTPベーシック認証、または認証なし（内部デプロイで一般的）をサポートします。

ツール

インストール

pip install jaeger-mcp

または、インストールせずに直接実行：

uvx jaeger-mcp

設定

すべての設定は環境変数を通じて行います：

.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を呼び出していますか？」

ツール利用ガイド

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を含む有向エッジ(親 → 子)を返します。lookback_hours（デフォルト24、最大720）を使用して期間を制御します。

パフォーマンス特性

• すべてのツールは、接続プーリングを備えた単一の永続的なrequests.Sessionを使用します。

• セッションはtrust_env = Falseに設定されており、環境プロキシをバイパスします（Jaegerは通常内部サービスであるため）。

• リクエストは30秒後にタイムアウトします。

• 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を参照してください。