jaeger-mcp

Servidor MCP para rastreo distribuido de Jaeger. Dale a Claude (o a cualquier agente compatible con MCP) acceso de lectura a tus datos de rastreo: busca rastreos, inspecciona spans, mapea dependencias de servicios, todo sin salir de la conversación.

¿Por qué otro MCP para Jaeger?

Las integraciones existentes de Jaeger requieren una interfaz de usuario en ejecución o scripts personalizados. Este servidor:

• Habla el Protocolo de Contexto de Modelo estándar a través de stdio: funciona con Claude Desktop, Claude Code, Cursor y cualquier cliente MCP.

• Es de solo lectura: las 5 herramientas incluyen readOnlyHint: true, por lo que no hay riesgo de modificar los datos de rastreo.

• Devuelve salida de doble canal: JSON estructurado (structuredContent) para uso programático + Markdown (content) para visualización legible por humanos.

• Tiene mensajes de error accionables que indican exactamente la variable de entorno a corregir y sugieren el siguiente paso.

• Admite token Bearer, autenticación HTTP Basic o sin autenticación (común para despliegues internos).

Herramientas

Instalación

pip install jaeger-mcp

O ejecútalo directamente sin instalar:

uvx jaeger-mcp

Configuración

Toda la configuración se realiza mediante variables de entorno:

Copia .env.example a .env y rellena tus valores.

Configuración de Claude Desktop / Claude Code

Añádelo a tu configuración de MCP (claude_desktop_config.json o .claude/mcp.json):

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

O con uvx (no requiere instalación):

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

Consultas de ejemplo

Una vez configurado, pregúntale a Claude:

• "¿Qué servicios conoce Jaeger?"

• "Busca rastreos con errores HTTP 500 en order-service de la última hora"

• "Muéstrame los rastreos más lentos (más de 2 segundos) para GET /checkout"

• "¿Qué causó el error en el rastreo abcdef1234567890?"

• "Mapea el grafo de dependencias de servicios de los últimos 7 días"

• "¿Qué servicios llaman a postgres con más frecuencia?"

Guía de uso de herramientas

jaeger_list_services

Devuelve todos los nombres de servicios que Jaeger ha visto. Empieza aquí cuando no sepas qué servicios están instrumentados. La salida está limitada a 500 servicios con una indicación de truncamiento.

jaeger_list_operations

Devuelve todos los nombres de operaciones para un servicio dado (p. ej., rutas HTTP, nombres de métodos gRPC). Úsalo para descubrir nombres de operaciones válidos antes de filtrar en jaeger_search_traces.

jaeger_search_traces

La herramienta de búsqueda principal. Filtros:

• service (requerido) — nombre del servicio de jaeger_list_services

• operation — limitar a un endpoint específico

• tags — cadena JSON de filtros de etiquetas, p. ej. {"http.status_code":"500"} o {"error":"true"}

• start / end — rango de tiempo en microsegundos UTC

• min_duration / max_duration — cadenas de duración como "100ms", "1.5s", "2m"

• limit — predeterminado 20, máximo 1500

Devuelve resúmenes de rastreo con trace_id, duration_us, span_count, service_count, root_operation, errors_count.

jaeger_get_trace

Detalle completo del rastreo. Acepta un trace_id (cadena hexadecimal, 16-32 caracteres) y devuelve:

• Todos los spans con etiquetas, nombres de servicio, relaciones padre/hijo

• Estadísticas por servicio (conteo de spans, duración total, conteo de errores)

• Árbol de ejecución (cada nodo lista los IDs de sus spans hijos)

Los spans con error se identifican mediante tags["error"] = "true".

jaeger_get_dependencies

Grafo de topología de servicios. Devuelve aristas dirigidas (padre → hijo) con call_count. Usa lookback_hours (predeterminado 24, máximo 720) para controlar la ventana de tiempo.

Características de rendimiento

• Todas las herramientas utilizan una única requests.Session persistente con agrupación de conexiones.

• La sesión tiene trust_env = False para omitir proxies de entorno (Jaeger suele ser un servicio interno).

• Las solicitudes tienen un tiempo de espera de 30 segundos.

• jaeger_search_traces pasa el limit directamente a Jaeger; evita solicitar más rastreos de los necesarios.

• jaeger_get_trace obtiene el rastreo completo en una sola llamada; los rastreos grandes (miles de spans) pueden ser lentos.

• jaeger_get_dependencies agrega datos sobre toda la ventana de tiempo; las ventanas grandes pueden ser lentas en clústeres ocupados.

Desarrollo

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

Licencia

MIT — ver LICENSE.