jaeger-mcp

MCP-Server für Jaeger verteiltes Tracing. Ermöglichen Sie Claude (oder jedem MCP-fähigen Agenten) Lesezugriff auf Ihre Trace-Daten — durchsuchen Sie Traces, untersuchen Sie Spans, bilden Sie Service-Abhängigkeiten ab — ohne die Unterhaltung zu verlassen.

Warum ein weiteres Jaeger-MCP?

Die bestehenden Jaeger-Integrationen erfordern eine laufende Benutzeroberfläche oder benutzerdefinierte Skripte. Dieser Server:

• Spricht das standardmäßige Model Context Protocol über stdio — funktioniert mit Claude Desktop, Claude Code, Cursor und jedem MCP-Client.

• Ist schreibgeschützt: alle 5 Tools tragen readOnlyHint: true — kein Risiko, Trace-Daten zu verändern.

• Liefert Dual-Channel-Ausgabe: strukturiertes JSON (structuredContent) für die programmatische Nutzung + Markdown (content) für die menschenlesbare Anzeige.

• Verfügt über umsetzbare Fehlermeldungen, die die genaue Umgebungsvariable nennen, die korrigiert werden muss, und einen nächsten Schritt vorschlagen.

• Unterstützt Bearer-Token, HTTP Basic Auth oder keine Authentifizierung (üblich für interne Bereitstellungen).

Tools

Installation

pip install jaeger-mcp

Oder führen Sie es direkt ohne Installation aus:

uvx jaeger-mcp

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen:

Kopieren Sie .env.example nach .env und tragen Sie Ihre Werte ein.

Claude Desktop / Claude Code Einrichtung

Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu (claude_desktop_config.json oder .claude/mcp.json):

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

Oder mit uvx (keine Installation erforderlich):

{
  "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

Beispielabfragen

Sobald die Konfiguration abgeschlossen ist, fragen Sie Claude:

• "Welche Services sind Jaeger bekannt?"

• "Finde Traces mit HTTP 500 Fehlern in order-service aus der letzten Stunde"

• "Zeige mir die langsamsten Traces (über 2 Sekunden) für GET /checkout"

• "Was hat den Fehler im Trace abcdef1234567890 verursacht?"

• "Erstelle den Service-Abhängigkeitsgraphen für die letzten 7 Tage"

• "Welche Services rufen postgres am häufigsten auf?"

Leitfaden zur Tool-Nutzung

jaeger_list_services

Gibt alle Servicenamen zurück, die Jaeger gesehen hat. Starten Sie hier, wenn Sie nicht wissen, welche Services instrumentiert sind. Die Ausgabe ist auf 500 Services mit einem Kürzungshinweis begrenzt.

jaeger_list_operations

Gibt alle Operationsnamen für einen bestimmten Service zurück (z. B. HTTP-Routen-Namen, gRPC-Methodennamen). Verwenden Sie dies, um gültige Operationsnamen zu entdecken, bevor Sie jaeger_search_traces filtern.

jaeger_search_traces

Das Hauptsuchwerkzeug. Filter:

• service (erforderlich) — Servicename aus jaeger_list_services

• operation — auf einen bestimmten Endpunkt eingrenzen

• tags — JSON-String von Tag-Filtern, z. B. {"http.status_code":"500"} oder {"error":"true"}

• start / end — Zeitbereich in Mikrosekunden UTC

• min_duration / max_duration — Dauer-Strings wie "100ms", "1.5s", "2m"

• limit — Standard 20, maximal 1500

Gibt Trace-Zusammenfassungen mit trace_id, duration_us, span_count, service_count, root_operation, errors_count zurück.

jaeger_get_trace

Vollständiges Trace-Detail. Akzeptiert eine trace_id (Hex-String, 16-32 Zeichen) und gibt zurück:

• Alle Spans mit Tags, Servicenamen, Eltern-/Kind-Beziehungen

• Statistiken pro Service (Span-Anzahl, Gesamtdauer, Fehleranzahl)

• Ausführungsbaum (jeder Knoten listet seine Kind-Span-IDs auf)

Fehler-Spans werden durch tags["error"] = "true" identifiziert.

jaeger_get_dependencies

Service-Topologie-Graph. Gibt gerichtete Kanten (Eltern → Kind) mit call_count zurück. Verwenden Sie lookback_hours (Standard 24, maximal 720), um das Zeitfenster zu steuern.

Leistungsmerkmale

• Alle Tools verwenden eine einzelne persistente requests.Session mit Verbindungspooling.

• Die Sitzung hat trust_env = False, um Umgebungsproxys zu umgehen (Jaeger ist typischerweise ein interner Service).

• Anfragen haben ein Timeout von 30 Sekunden.

• jaeger_search_traces übergibt limit direkt an Jaeger — vermeiden Sie es, mehr Traces anzufordern als nötig.

• jaeger_get_trace ruft das vollständige Trace in einem Aufruf ab — große Traces (Tausende von Spans) können langsam sein.

• jaeger_get_dependencies aggregiert über das gesamte Lookback-Fenster; große Fenster können in ausgelasteten Clustern langsam sein.

Entwicklung

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

Lizenz

MIT — siehe LICENSE.