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 基本认证 或 无认证（内部部署常见）。

工具

安装

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 知道哪些服务？”

• “查找过去一小时内 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 字符）并返回：

• 所有带有标签、服务名称、父/子关系的跨度

• 每个服务的统计信息（跨度计数、总持续时间、错误计数）

• 执行树（每个节点列出其子跨度 ID）

错误跨度由 tags["error"] = "true" 标识。

jaeger_get_dependencies

服务拓扑图。返回带有 call_count 的有向边 (parent → child)。使用 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。