{
  "markdown": "# jaeger-mcp\n\n<!-- mcp-name: io.github.mshegolev/jaeger-mcp -->\n\n[![PyPI version](https://img.shields.io/pypi/v/jaeger-mcp.svg)](https://pypi.org/project/jaeger-mcp/)\n[![Python versions](https://img.shields.io/pypi/pyversions/jaeger-mcp.svg)](https://pypi.org/project/jaeger-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Tests](https://github.com/mshegolev/jaeger-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/mshegolev/jaeger-mcp/actions/workflows/test.yml)\n\n**MCP server for [Jaeger](https://www.jaegertracing.io/) distributed tracing.**\nGive Claude (or any MCP-capable agent) read access to your trace data — search traces, inspect spans, compare traces, compute span statistics, map service dependencies, predict performance issues, and forecast capacity needs — without leaving the conversation.\n\n## Why another Jaeger MCP?\n\nThe existing Jaeger integrations require a running UI or custom scripts. This server:\n\n- Speaks the standard [Model Context Protocol](https://modelcontextprotocol.io/) over **stdio** — works with Claude Desktop, Claude Code, Cursor, and any MCP client.\n- Is **read-only**: all 15 tools carry `readOnlyHint: true` — zero risk of modifying trace data.\n- Returns **dual-channel output**: structured JSON (`structuredContent`) for programmatic use + Markdown (`content`) for human-readable display.\n- Has **actionable error messages** that name the exact env var to fix and suggest a next step.\n- Supports **Bearer token**, **HTTP Basic auth**, or **no auth** (common for internal deployments).\n- Includes **OpenAPI specification** documenting the underlying Jaeger Query API (`openapi.yaml`).\n\n## Tools\n\n| Tool | Endpoint | Description |\n|------|----------|-------------|\n| `jaeger_list_services` | `GET /api/services` | List all instrumented services |\n| `jaeger_list_operations` | `GET /api/services/{service}/operations` | List operation names for a service |\n| `jaeger_search_traces` | `GET /api/traces` | Search traces with rich filters |\n| `jaeger_get_trace` | `GET /api/traces/{traceID}` | Full trace detail with span tree |\n| `jaeger_get_dependencies` | `GET /api/dependencies` | Service-to-service call graph |\n| `jaeger_compare_traces` | `GET /api/traces/{traceID}` ×2 | Structural diff between two traces |\n| `jaeger_span_statistics` | `GET /api/traces` | Per-operation latency and error stats |\n| `jaeger_critical_path` | `GET /api/traces/{traceID}` | Longest-duration span chain and bottleneck ranking |\n| `jaeger_compare_windows` | `GET /api/traces` ×2 | Aggregate trace behavior diff between two time periods |\n| `jaeger_detect_anomalies` | `GET /api/traces` ×2 | Statistical latency/error-rate spike detection per operation |\n| `jaeger_predict_degradation` | `GET /api/traces` | Predict performance degradation 2-24 hours in advance |\n| `jaeger_forecast_capacity` | `GET /api/traces` | Forecast throughput demands and resource requirements |\n| `jaeger_find_test_traces` | `GET /api/traces` | Correlate a test run to its traces by tag query (Allure/pytest/custom) |\n| `jaeger_regression_diff` | `GET /api/traces` ×2 | Classify per-operation regressions between two time windows |\n| `jaeger_test_profile` | `GET /api/traces` | Per-operation latency hotspots for a tagged test run |\n\n## Installation\n\n```bash\npip install jaeger-mcp\n```\n\nOr run directly without installing:\n\n```bash\nuvx jaeger-mcp\n```\n\n## Configuration\n\nAll configuration is via environment variables:\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `JAEGER_URL` | **Yes** | — | Jaeger query service URL, e.g. `https://jaeger.example.com` |\n| `JAEGER_TOKEN` | No | — | Bearer token (takes precedence over Basic auth) |\n| `JAEGER_USERNAME` | No | — | HTTP Basic auth username |\n| `JAEGER_PASSWORD` | No | — | HTTP Basic auth password |\n| `JAEGER_SSL_VERIFY` | No | `true` | Set `false` for self-signed certificates |\n| `JAEGER_TIMEOUT` | No | `30` | HTTP request timeout in seconds |\n| `JAEGER_RETRY_ATTEMPTS` | No | `3` | Retry count for transient failures (0 to disable) |\n| `JAEGER_CACHE_TTL` | No | `120` | TTL in seconds for discovery endpoint cache (0 to disable) |\n\nCopy `.env.example` to `.env` and fill in your values.\n\n## Claude Desktop / Claude Code setup\n\nAdd to your MCP config (`claude_desktop_config.json` or `.claude/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"jaeger\": {\n      \"command\": \"jaeger-mcp\",\n      \"env\": {\n        \"JAEGER_URL\": \"https://jaeger.example.com\",\n        \"JAEGER_TOKEN\": \"your-token-here\"\n      }\n    }\n  }\n}\n```\n\nOr with `uvx` (no install required):\n\n```json\n{\n  \"mcpServers\": {\n    \"jaeger\": {\n      \"command\": \"uvx\",\n      \"args\": [\"jaeger-mcp\"],\n      \"env\": {\n        \"JAEGER_URL\": \"https://jaeger.example.com\"\n      }\n    }\n  }\n}\n```\n\n## Docker\n\n```bash\ndocker run --rm -e JAEGER_URL=https://jaeger.example.com jaeger-mcp\n```\n\n## Example queries\n\nOnce configured, ask Claude:\n\n- \"What services does Jaeger know about?\"\n- \"Find traces with HTTP 500 errors in `order-service` from the last hour\"\n- \"Show me the slowest traces (over 2 seconds) for `GET /checkout`\"\n- \"What caused the error in trace `abcdef1234567890`?\"\n- \"Map the service dependency graph for the last 7 days\"\n- \"Which services call `postgres` most frequently?\"\n- \"Compare trace `abc123` against trace `def456` — what spans changed?\"\n- \"What are the p95 latencies per operation in `order-service`?\"\n\n## Tool usage guide\n\n### `jaeger_list_services`\n\nReturns all service names Jaeger has seen. **Start here** when you don't know which services are instrumented. Output is capped at 500 services with a truncation hint.\n\n### `jaeger_list_operations`\n\nReturns all operation names for a given service (e.g. HTTP route names, gRPC method names). Use to discover valid operation names before filtering `jaeger_search_traces`.\n\n### `jaeger_search_traces`\n\nThe main search tool. Filters:\n\n- `service` (required) — service name from `jaeger_list_services`\n- `operation` — narrow to a specific endpoint\n- `tags` — JSON string of tag filters, e.g. `{\"http.status_code\":\"500\"}` or `{\"error\":\"true\"}`\n- `start` / `end` — time range in **microseconds** UTC\n- `min_duration` / `max_duration` — duration strings like `\"100ms\"`, `\"1.5s\"`, `\"2m\"`\n- `limit` — default 20, max 1500\n\nReturns trace summaries with `trace_id`, `duration_us`, `span_count`, `service_count`, `root_operation`, `errors_count`.\n\n### `jaeger_get_trace`\n\nFull trace detail. Accepts a `trace_id` (hex string, 16-32 chars) and returns:\n\n- All spans with tags, service names, parent/child relationships\n- Per-service statistics (span count, total duration, error count)\n- Execution tree (each node lists its child span IDs)\n\nError spans are identified by `tags[\"error\"] = \"true\"`.\n\n### `jaeger_get_dependencies`\n\nService topology graph. Returns directed edges `(parent → child)` with `call_count`. Use `lookback_hours` (default 24, max 720) to control the window.\n\n### `jaeger_compare_traces`\n\nStructural diff between two traces. Accepts two `trace_id` hex strings and matches spans by `(operationName, serviceName, parentOperation)` — not span ID. Reports:\n\n- **Added spans** — present in trace B but not trace A\n- **Removed spans** — present in trace A but not trace B\n- **Changed spans** — matched but differ in duration or tags (shows deltas)\n- **Unchanged count** — number of identical spans\n\nUse to compare a slow trace against a fast one, or to see what changed between deployments.\n\n### `jaeger_span_statistics`\n\nPer-operation latency percentiles and error rates. Fetches up to `limit` traces (default 20, max 100) for a service and aggregates all spans by operation name. Reports per operation:\n\n- `count` — total spans observed\n- `p50_duration_us`, `p95_duration_us`, `p99_duration_us` — latency percentiles\n- `error_count`, `error_rate` — errors (identified by `tags[\"error\"] = \"true\"`)\n\nUse to find the slowest or most error-prone operations in a service.\n\n### `jaeger_critical_path`\n\nIdentifies the longest-duration span chain from root to leaf in a trace (the critical path) and ranks spans by self-time to find performance bottlenecks. \n\nReports:\n- Critical path spans with operation, service, duration, and percentage-of-total\n- Bottleneck spans ranked by exclusive duration (self-time)\n\nUse to answer \"Why is this trace so slow?\" and \"Which operations consume the most CPU/self-time?\"\n\n### `jaeger_compare_windows`\n\nCompares aggregate trace behavior between two time periods for a service to detect performance regressions or improvements across deployments.\n\nReports:\n- Per-operation diff summary showing added, removed, faster, slower operations\n- Deviation scoring with numeric scores per operation and overall\n- Latency percentile changes (p50, p95) and error rate deltas\n\nUse to answer \"Did our latest deployment affect performance?\" and \"Which operations got slower after the database upgrade?\"\n\n### `jaeger_detect_anomalies`\n\nScans for statistically significant latency spikes or error-rate increases in a service's recent traces compared to historical baselines.\n\nReports:\n- Flagged operations with anomaly type (latency or error_rate)\n- Severity classification (low to critical) with z-scores\n- Current vs baseline values for affected metrics\n\nUse to proactively identify performance degradations and reliability issues before they impact users.\n\n## Library facade (in-process use)\n\n`jaeger-mcp` can also be used as a Python library without an MCP server:\n\n```python\nfrom jaeger_mcp import JaegerClient\n\nclient = JaegerClient.from_env()  # reads JAEGER_URL from env\ntrace = client.get_trace(\"abcdef1234567890abcdef1234567890\")\n\nfor span in trace.spans:\n    if span.error:\n        print(f\"{span.service_name}: {span.operation} at {span.start_utc}\")\n        print(f\"  tags: {span.tags}\")\n```\n\nAvailable methods: `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()`.\n\nDomain objects: `Span`, `Trace`, `TraceSummary`, `ServiceDep`, `TraceComparison`, `SpanIdentity`, `SpanChange`, `SpanStatisticsResult`, `OperationStatResult`, `CriticalPathOutput`, `CriticalPathSpan`, `BottleneckSpan`, `WindowComparisonOutput`, `OperationDiff`, `AnomalyDetectionOutput`, `OperationAnomaly` — all with typed fields.\n\n## API Documentation\n\nThis project includes comprehensive OpenAPI specifications in the `docs/` directory:\n\n1. **Jaeger Query Service API** (`openapi.yaml`) - Documents the actual Jaeger API endpoints\n2. **MCP Tools API** (`docs/mcp-tools-openapi.yaml`) - Documents the MCP tools as conceptual HTTP endpoints\n\nThese specifications are useful for:\n- Understanding the underlying API calls made by each tool\n- Developing alternative integrations\n- Debugging API interactions\n- Generating client libraries or documentation\n\nSee `docs/README.md` for more details on both specifications.\n\n## Performance characteristics\n\n- All tools use a single persistent `requests.Session` with connection pooling.\n- The session has `trust_env = False` to bypass environment proxies (Jaeger is typically an internal service).\n- Requests time out after 30 seconds (configurable via `JAEGER_TIMEOUT`).\n- Transient HTTP errors (429/5xx) are retried with exponential backoff (configurable via `JAEGER_RETRY_ATTEMPTS`).\n- `list_services` and `list_operations` responses are cached for 120 seconds (configurable via `JAEGER_CACHE_TTL`).\n- `jaeger_search_traces` passes `limit` directly to Jaeger — avoid requesting more traces than needed.\n- `jaeger_get_trace` fetches the full trace in one call — large traces (thousands of spans) may be slow.\n- `jaeger_get_dependencies` aggregates over the full lookback window; large windows may be slow on busy clusters.\n\n## Development\n\n```bash\ngit clone https://github.com/mshegolev/jaeger-mcp\ncd jaeger-mcp\npip install -e '.[dev]'\npytest tests/ -v\nruff check src tests\nruff format src tests\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 12087,
  "sha": "692733f13844ed92b82fd96d46faf64f9f90b5d3f7d5bbe31ca2300822278761",
  "repo_slug": "mshegolev/jaeger-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mshegolev_jaeger_mcp_9cad4580/readme"
}