Skip to main content
Glama

jaeger-mcp

PyPI version Python versions License: MIT Tests

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).

Related MCP server: otel-mcp

Tools

Tool

Endpunkt

Beschreibung

jaeger_list_services

GET /api/services

Alle instrumentierten Services auflisten

jaeger_list_operations

GET /api/services/{service}/operations

Operationsnamen für einen Service auflisten

jaeger_search_traces

GET /api/traces

Traces mit umfangreichen Filtern suchen

jaeger_get_trace

GET /api/traces/{traceID}

Vollständiges Trace-Detail mit Span-Baum

jaeger_get_dependencies

GET /api/dependencies

Service-zu-Service-Aufrufgraph

Installation

pip install jaeger-mcp

Oder führen Sie es direkt ohne Installation aus:

uvx jaeger-mcp

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen:

Variable

Erforderlich

Standard

Beschreibung

JAEGER_URL

Ja

—

Jaeger Query-Service-URL, z. B. https://jaeger.example.com

JAEGER_TOKEN

Nein

—

Bearer-Token (hat Vorrang vor Basic Auth)

JAEGER_USERNAME

Nein

—

HTTP Basic Auth Benutzername

JAEGER_PASSWORD

Nein

—

HTTP Basic Auth Passwort

JAEGER_SSL_VERIFY

Nein

true

Auf false setzen für selbstsignierte Zertifikate

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.

Available Tools

15 tools
jaeger_compare_tracesA
Read-onlyIdempotent

Compare two traces structurally — find added, removed, and changed spans.

Fetches both traces from Jaeger and performs a structural diff by matching spans on (operationName, serviceName, parentOperation) — not span IDs, which differ across traces. Reports duration deltas and tag differences for changed spans.

Examples: - Use when: "What changed between a fast and slow request?" → pass the trace IDs of both requests; inspect changed_spans for duration deltas. - Use when: "Did a deployment add new service calls?" → compare a pre-deploy trace with a post-deploy trace; check added_spans for new operations. - Use when: "Are these two traces structurally identical?" → if added_spans, removed_spans, and changed_spans are all empty, the traces have the same structure. - Don't use when: You want aggregate statistics across many traces (use jaeger_span_statistics instead, once available). - Don't use when: You only have one trace — use jaeger_get_trace for single-trace inspection.

Returns: dict with trace_id_a / trace_id_b / added_spans / removed_spans / changed_spans (with duration + tag deltas) / unchanged_count.

Inputs: trace_id_a (required), trace_id_b (required). Returns: trace_id_a, trace_id_b, added_spans, changed_spans, +2 more

jaeger_compare_windowsA
Read-onlyIdempotent

Compare aggregate trace behavior between two time periods for a service.

Fetches traces from both time windows, aggregates span statistics per operation, then compares the aggregate behavior to detect performance changes.

Examples: - Use when: "Did our latest deployment affect performance?" → compare pre-deploy and post-deploy time windows for the service. - Use when: "Which operations got slower after the database upgrade?" → check the comparison_p95_us and p95_delta_pct columns for increases. - Use when: "Are we seeing new error patterns?" → look for operations with increased error_rate_delta. - Use when: "Did we add or remove any API endpoints?" → check added_count and removed_count in the summary. - Don't use when: You want to compare two specific traces (use jaeger_compare_traces instead). - Don't use when: You want full span detail for a single trace (use jaeger_get_trace instead).

Returns: WindowComparisonOutput with per-operation diffs and summary statistics.

Inputs: service (required), baseline_end (required), baseline_start (required), comparison_end (required), +3 more. Returns: service, operations, added_count, baseline_end, +8 more

jaeger_critical_pathA
Read-onlyIdempotent

Identify the critical path and top bottlenecks in a trace.

Finds the longest-duration span chain (critical path) from root to leaf, and ranks spans by self-time to find actual performance bottlenecks.

Examples: - Use when: "Why is this trace so slow?" → call with the slow trace ID; examine the critical_path_duration_us and critical_path_percentage to see how much of the total time is spent on the longest path. - Use when: "Which operations are consuming the most CPU/self-time?" → check the bottlenecks list sorted by self_time_us descending. - Use when: Debugging performance regressions — compare critical path percentages before/after changes. - Don't use when: You want aggregate statistics across many traces (use jaeger_span_statistics for that). - Don't use when: You need to compare two traces structurally (use jaeger_compare_traces for that).

Returns: dict with trace metadata, critical path spans, and bottleneck ranking.

Inputs: trace_id (required). Returns: trace_id, bottlenecks, critical_path, root_operation, +4 more

jaeger_detect_anomaliesA
Read-onlyIdempotent

Detect latency and error-rate anomalies for a service by comparing recent behavior to historical baseline.

Fetches traces from a historical baseline window and a recent observation window, computes per-operation statistics for both, then identifies statistically significant deviations that may indicate performance issues or reliability problems.

Examples: - Use when: "Are there any new performance issues in order-service?" → service='order-service' (uses default 60-minute baseline, 5-minute current). - Use when: "Be more sensitive to subtle changes" → set sensitivity=1.5 (lower threshold). - Use when: "Check for issues over the last 24 hours against previous week" → baseline_duration_minutes=10080, current_duration_minutes=1440. - Don't use when: You want to compare two specific time periods (use jaeger_compare_windows instead). - Don't use when: You want full span detail for a single trace (use jaeger_get_trace instead).

Returns: AnomalyDetectionOutput with flagged operations and severity scores.

Inputs: service (required), sensitivity, current_duration_minutes, baseline_duration_minutes. Returns: service, anomalies, current_end, sensitivity, +6 more

jaeger_find_test_tracesA
Read-onlyIdempotent

Find Jaeger traces matching the supplied tag query.

Accepts any tag key-value schema (Allure, pytest, custom) without normalization. When service is omitted, searches all known services concurrently (capped at 20). Results are sorted newest-first.

Inputs: tags (required), limit, service, lookback_hours. Returns: traces, tag_query, total_count, service_filter

jaeger_forecast_capacityA
Read-onlyIdempotent

Forecast future throughput demands and resource requirements for a service.

Provides predictions for the next 7-30 days with confidence intervals to enable infrastructure scaling decisions.

Args: service: Service name to forecast capacity for days_ahead: Number of days to forecast ahead (default: 30 days)

Returns: ForecastResult with throughput predictions and resource requirements

Inputs: service (required), days_ahead. Returns: Result of a capacity forecasting prediction.

jaeger_get_dependenciesA
Read-onlyIdempotent

Retrieve the service-to-service call graph from Jaeger.

Wraps GET /api/dependencies. Returns directed edges (parent → child) with call_count — the number of spans where parent called child in the lookback window.

Use this to understand service topology, find high fan-out services, or verify that a new service is connected as expected.

Examples: - Use when: "What services does order-service call?" → check edges where parent='order-service'. - Use when: "Map the full service dependency graph for the last 7 days" → lookback_hours=168. - Use when: "Which services are called most frequently?" → sort edges by call_count descending. - Don't use when: You want detailed span timings (use jaeger_search_traces + jaeger_get_trace instead). - Don't use when: You need real-time data — Jaeger's dependency graph is aggregated and may lag by minutes.

Returns: dict with end_ts_us / lookback_hours / edge_count / edges (list of {parent, child, call_count}).

Inputs: end_ts, lookback_hours. Returns: edges, end_ts_us, edge_count, lookback_hours

jaeger_get_traceA
Read-onlyIdempotent

Retrieve full trace detail with all spans, service breakdown, and execution tree.

Wraps GET /api/traces/{traceID}. Returns every span in the trace, per-service statistics, and a flat execution tree (each node lists its child span IDs) that summarises the call hierarchy.

Error spans are identified by tags["error"] = "true".

Examples: - Use when: "Why is trace abc123... slow — show me the span breakdown" → trace_id='abc123...'; inspect services for the heaviest service and execution_tree for the call hierarchy. - Use when: "Which service caused the error in trace xyz...?" → check spans where is_error=true. - Use when: You found a slow/failed trace in jaeger_search_traces and need full detail. - Don't use when: You don't have a specific traceID — use jaeger_search_traces to find one first. - Don't use when: You only want aggregate data across many traces (use jaeger_search_traces with filters instead).

Returns: dict with trace_id / span_count / service_count / root_operation / root_service / start_time_us / total_duration_us / errors_count / services (per-service stats) / spans (all spans) / execution_tree.

Inputs: trace_id (required). Returns: spans, services, trace_id, span_count, +7 more

jaeger_list_operationsA
Read-onlyIdempotent

List all operation names Jaeger has seen for a given service.

Wraps GET /api/services/{service}/operations. Useful for discovering which operation names to pass as filters to jaeger_search_traces. Output is capped at 500 operations.

Examples: - Use when: "What HTTP endpoints does order-service expose in tracing?" → service='order-service'. - Use when: You want to search for a specific slow operation but need the exact name — list operations first, then pass it to jaeger_search_traces. - Use when: Auditing which gRPC methods a service traces. - Don't use when: You don't have a specific service — start with jaeger_list_services first. - Don't use when: You want to search traces immediately (skip this step if you already know the operation name).

Returns: dict with service / operations_count / truncated / operations (sorted alphabetically).

Inputs: service (required). Returns: service, truncated, operations, operations_count

jaeger_list_servicesA
Read-onlyIdempotent

List all services that Jaeger has observed traces for.

Wraps GET /api/services. Jaeger returns all services at once — no pagination. Output is capped at 500 services with a truncation hint.

Use this first to discover valid service names before calling jaeger_list_operations or jaeger_search_traces.

Examples: - Use when: "What services does Jaeger know about?" → call with no parameters; read the services list. - Use when: "Is payment-service instrumented?" → check if payment-service appears in the services list. - Use when: Starting a debugging session — list services first, then pick one for jaeger_list_operations or jaeger_search_traces. - Don't use when: You already know the service name and want to search its traces (call jaeger_search_traces directly). - Don't use when: You want the dependency graph between services (call jaeger_get_dependencies).

Returns: dict with keys services_count / truncated / services.

Inputs: no named parameters. Returns: services, truncated, services_count

jaeger_predict_degradationA
Read-onlyIdempotent

Predict potential performance degradation events for a service.

Analyzes historical trace data patterns, critical path trends, and anomaly detection results to forecast likely performance issues 2-24 hours in advance.

Args: service: Service name to analyze for potential degradation hours_back: Number of hours of historical data to analyze (default: 168 hours/1 week)

Returns: PredictionResult with degradation forecast, confidence level, and recommendations

Inputs: service (required), hours_back. Returns: Result of a performance degradation prediction.

jaeger_regression_diffA
Read-onlyIdempotent

Compare two Jaeger time windows and classify per-operation regressions.

Fetches traces from the baseline and comparison windows, then classifies each operation as regressed, recovered, appeared, or removed. Results are sorted by severity score (0-100) descending for easy triage.

Inputs: service (required), baseline_end (required), baseline_start (required), limit, +2 more. Returns: service, operations, baseline_end, removed_count, +6 more

jaeger_search_tracesA
Read-onlyIdempotent

Search Jaeger traces with rich filters.

Wraps GET /api/traces. Returns a list of trace summaries — use jaeger_get_trace to drill into a specific trace for span details.

The tags parameter accepts a JSON string so the LLM can construct arbitrary tag filters. Durations (min_duration/max_duration) are forwarded as-is to Jaeger (e.g. '100ms', '1.5s').

Examples: - Use when: "Show me recent 500 errors in order-service" → service='order-service', tags='{"http.status_code":"500"}'. - Use when: "Find slow traces (>1s) for checkout endpoint" → service='checkout', operation='POST /checkout', min_duration='1s'. - Use when: "Give me the last 5 traces in the last hour" → limit=5, set start to (now - 3600s) in microseconds. - Don't use when: You already have a traceID and want full details (call jaeger_get_trace directly — one fewer round trip). - Don't use when: You want service dependency topology (call jaeger_get_dependencies).

Returns: dict with service / operation / returned / truncated / traces (list of :class:TraceSummary).

Inputs: service (required), end, tags, limit, +4 more. Returns: traces, service, returned, operation, +1 more

jaeger_span_statisticsA
Read-onlyIdempotent

Compute per-operation latency percentiles and error rates across recent traces.

Fetches up to limit traces for the given service (optionally filtered by operation), then aggregates all spans by operation name. For each operation reports: span count, p50/p95/p99 duration in microseconds, error count, and error rate.

Duration values are in microseconds (integer). Error rate is error_count / span_count (float, 0.0–1.0).

Examples: - Use when: "What are the p95 latencies for each endpoint in order-service?" → service='order-service'; inspect each operation's p95_duration_us. - Use when: "How often does the POST /checkout endpoint error?" → service='checkout-svc', operation='POST /checkout'; check error_rate in the stats. - Use when: "Compare latency distributions across operations" → look at p50 vs p99 spread to identify high-variance operations. - Use when: "Get a larger sample for more accurate stats" → limit=100 for higher confidence percentiles. - Don't use when: You want to compare two specific traces (use jaeger_compare_traces instead). - Don't use when: You want full span detail for a single trace (use jaeger_get_trace instead).

Returns: dict with service / operation / trace_count / stats (list of per-operation stats with count, p50/p95/p99 duration_us, error_count, error_rate).

Inputs: service (required), limit, operation. Returns: stats, service, operation, trace_count

jaeger_test_profileA
Read-onlyIdempotent

Aggregate per-operation latency hotspots across all traces matching the supplied tag query.

Operations are ranked by total wall time descending so the most expensive appear first.

Inputs: tags (required), limit, service, lookback_hours. Returns: tag_query, operations, trace_count, service_filter

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 15 tools

    Disambiguation2/5

    Several tools have overlapping purposes. jaeger_search_traces and jaeger_find_test_traces both search traces with tag filters, and jaeger_compare_windows, jaeger_detect_anomalies, and jaeger_regression_diff all compare two time windows to identify performance changes, making it easy for an agent to select the wrong one. The differences between these are subtle and not clearly delineated.

    Naming Consistency3/5

    All tools share the jaeger_ prefix and use snake_case, but the naming pattern is inconsistent: some are verb_noun (list_services, search_traces) while others are noun_phrase (span_statistics, critical_path, test_profile). This mixed convention is readable but lacks the predictability of a uniform verb_noun scheme.

    Tool Count4/5

    15 tools is at the upper boundary of a well-scoped set, but the advanced analytics tools (predict_degradation, forecast_capacity, detect_anomalies) expand the server's capability beyond basic tracing. The count is reasonable, though some tools could be merged without losing functionality.

    Completeness4/5

    The core Jaeger read operations are fully covered: service discovery, operation listing, trace search, trace detail, and dependency graph. Advanced analytics like comparisons, anomaly detection, and predictions provide extra depth, leaving few obvious gaps for a tracing-focused server.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables to interact with Jaeger distributed tracing system through the MCP protocol. Supports querying traces, services, and operations via natural language.
      89 npm
      19
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that gives AI agents access to your application's OpenTelemetry traces for querying, analysis, and debugging.
      5
      11 npm
      2
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables querying and analyzing distributed traces from Jaeger, including service discovery, trace inspection, and performance analysis, through MCP tools.
      7
      2
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server for querying Jaeger environments from Codex, returning compact, sanitized trace summaries to protect sensitive data.
      1
      -