jaeger-mcp
jaeger-mcp
Jaeger 분산 추적을 위한 MCP 서버입니다. Claude(또는 모든 MCP 지원 에이전트)에게 추적 데이터에 대한 읽기 액세스 권한을 부여하여 대화를 떠나지 않고도 추적 검색, 스팬 검사, 서비스 종속성 매핑을 수행할 수 있습니다.
왜 또 다른 Jaeger MCP인가요?
기존 Jaeger 통합은 실행 중인 UI나 사용자 지정 스크립트가 필요합니다. 이 서버는 다음과 같은 특징이 있습니다:
stdio를 통해 표준 Model Context Protocol을 사용하므로 Claude Desktop, Claude Code, Cursor 및 모든 MCP 클라이언트와 호환됩니다.
읽기 전용: 5개의 도구 모두
readOnlyHint: true를 포함하고 있어 추적 데이터를 수정할 위험이 전혀 없습니다.이중 채널 출력: 프로그래밍 방식으로 사용할 수 있는 구조화된 JSON(
structuredContent)과 사람이 읽을 수 있는 Markdown(content)을 모두 반환합니다.실행 가능한 오류 메시지: 수정해야 할 정확한 환경 변수를 명시하고 다음 단계를 제안합니다.
인증 지원: Bearer 토큰, HTTP Basic 인증 또는 인증 없음(내부 배포 시 일반적)을 지원합니다.
Related MCP server: otel-mcp
도구
도구 | 엔드포인트 | 설명 |
|
| 계측된 모든 서비스 나열 |
|
| 서비스의 작업 이름 나열 |
|
| 풍부한 필터로 추적 검색 |
|
| 스팬 트리를 포함한 전체 추적 세부 정보 |
|
| 서비스 간 호출 그래프 |
설치
pip install jaeger-mcp또는 설치 없이 직접 실행:
uvx jaeger-mcp구성
모든 구성은 환경 변수를 통해 이루어집니다:
변수 | 필수 | 기본값 | 설명 |
| 예 | — | Jaeger 쿼리 서비스 URL (예: |
| 아니요 | — | Bearer 토큰 (Basic 인증보다 우선) |
| 아니요 | — | HTTP Basic 인증 사용자 이름 |
| 아니요 | — | HTTP Basic 인증 비밀번호 |
| 아니요 |
| 자체 서명된 인증서의 경우 |
.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는 한 번의 호출로 전체 추적을 가져오므로 대규모 추적(수천 개의 스팬)은 느릴 수 있습니다.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를 참조하세요.
Available Tools
15 toolsjaeger_compare_tracesARead-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_windowsARead-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_pathARead-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_anomaliesARead-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_tracesARead-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_capacityARead-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_dependenciesARead-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_traceARead-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_operationsARead-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_servicesARead-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_degradationARead-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_diffARead-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_tracesARead-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_statisticsARead-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_profileARead-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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
MCP observability. Query live traffic, errors, duration, and alerts from your AI agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables to interact with Jaeger distributed tracing system through the MCP protocol. Supports querying traces, services, and operations via natural language.89 npm19MIT
- AlicenseAqualityDmaintenanceMCP server that gives AI agents access to your application's OpenTelemetry traces for querying, analysis, and debugging.511 npm2MIT
- AlicenseBqualityDmaintenanceEnables querying and analyzing distributed traces from Jaeger, including service discovery, trace inspection, and performance analysis, through MCP tools.72Apache 2.0
- FlicenseNot gradedqualityDmaintenanceRead-only MCP server for querying Jaeger environments from Codex, returning compact, sanitized trace summaries to protect sensitive data.1-