Tempo MCP Server

Un servidor MCP para consultar datos de trazado distribuido desde Grafana Tempo.

Documentación

Tempo MCP Server

Una implementación de servidor en Go para el Protocolo de Contexto de Modelo (MCP) con integración de Grafana Tempo.

Descripción general

Este servidor MCP permite a los asistentes de IA consultar y analizar datos de trazado distribuido de Grafana Tempo. Sigue el Protocolo de Contexto de Modelo para proporcionar definiciones de herramientas que pueden ser utilizadas por clientes de IA compatibles, como Claude Desktop.

Primeros pasos

Requisitos previos

Go 1.21 o superior
Docker y Docker Compose (para pruebas locales)

Compilación y ejecución

Compila y ejecuta el servidor:

# Build the server
go build -o tempo-mcp-server ./cmd/server

# Run the server
./tempo-mcp-server

O ejecuta directamente con Go:

go run ./cmd/server

El servidor ahora admite dos modos de comunicación:

Entrada/salida estándar (stdin/stdout) siguiendo el Protocolo de Contexto de Modelo (MCP)
Servidor HTTP con endpoint de Server-Sent Events (SSE) para integración con herramientas como n8n

El puerto predeterminado para el servidor HTTP es 8080, pero se puede configurar usando la variable de entorno SSE_PORT.

Endpoints del servidor

Cuando se ejecuta en modo HTTP, el servidor expone los siguientes endpoints:

Endpoint SSE: http://localhost:8080/sse - Para transmisión de eventos en tiempo real
Endpoint MCP: http://localhost:8080/mcp - Para mensajería del protocolo MCP

Soporte de Docker

Puedes compilar y ejecutar el servidor MCP usando Docker:

# Build the Docker image
docker build -t tempo-mcp-server .

# Run the server
docker run -p 8080:8080 --rm -i tempo-mcp-server

Alternativamente, puedes usar Docker Compose para un entorno de prueba completo:

# Build and run with Docker Compose
docker-compose up --build

Estructura del proyecto

.
├── cmd/
│   ├── server/       # MCP server implementation
│   └── client/       # Client for testing the MCP server
├── internal/
│   └── handlers/     # Tool handlers
├── pkg/
│   └── utils/        # Utility functions and shared code
└── go.mod            # Go module definition

Servidor MCP

El servidor MCP de Tempo implementa el Protocolo de Contexto de Modelo (MCP) y proporciona las siguientes herramientas:

Herramienta de consulta de Tempo

La herramienta tempo_query te permite consultar datos de trazas de Grafana Tempo:

Parámetros requeridos:
- query: Cadena de consulta de Tempo (por ejemplo, {service.name="frontend"}, {duration>1s})
Parámetros opcionales:
- url: La URL del servidor de Tempo (predeterminado: de la variable de entorno TEMPO_URL o http://localhost:3200)
- start: Hora de inicio para la consulta (predeterminado: hace 1 hora)
- end: Hora de finalización para la consulta (predeterminado: ahora)
- limit: Número máximo de trazas a devolver (predeterminado: 20)
- username: Nombre de usuario para autenticación básica (opcional)
- password: Contraseña para autenticación básica (opcional)
- token: Token de portador para autenticación (opcional)

Variables de entorno

La herramienta de consulta de Tempo admite las siguientes variables de entorno:

TEMPO_URL: URL del servidor de Tempo predeterminada para usar si no se especifica en la solicitud
SSE_PORT: Puerto para el servidor HTTP/SSE (predeterminado: 8080)

Pruebas

./run-client.sh tempo_query "{resource.service.name=\\\"example-service\\\"}"

Uso con Claude Desktop

Puedes usar este servidor MCP con Claude Desktop para agregar herramientas de consulta de Tempo. Sigue estos pasos:

Compila el servidor o la imagen de Docker
Configura Claude Desktop para usar el servidor agregándolo a tu archivo de configuración de Claude Desktop

Ejemplo de configuración de Claude Desktop:

{
  "mcpServers": {
    "temposerver": {
      "command": "path/to/tempo-mcp-server",
      "args": [],
      "env": {
        "TEMPO_URL": "http://localhost:3200"
      },
      "disabled": false,
      "autoApprove": ["tempo_query"]
    }
  }
}

Para Docker:

{
  "mcpServers": {
    "temposerver": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "TEMPO_URL=http://host.docker.internal:3200", "tempo-mcp-server"],
      "disabled": false,
      "autoApprove": ["tempo_query"]
    }
  }
}

El archivo de configuración de Claude Desktop se encuentra en:

En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
En Windows: %APPDATA%\Claude\claude_desktop_config.json
En Linux: ~/.config/Claude/claude_desktop_config.json

Uso con Cursor

También puedes integrar el servidor MCP de Tempo con el editor Cursor. Para hacerlo, agrega la siguiente configuración a tu configuración de Cursor:

{
  "mcpServers": {
    "tempo-mcp-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "TEMPO_URL=http://host.docker.internal:3200", "tempo-mcp-server:latest"]
    }
  }
}

Uso con n8n

Para usar el servidor MCP de Tempo con n8n, puedes conectarte a él usando el nodo MCP Client Tool:

Agrega un nodo MCP Client Tool a tu flujo de trabajo de n8n
Configura el nodo con estos parámetros:
- SSE Endpoint: http://your-server-address:8080/sse (reemplaza con la dirección real de tu servidor)
- Authentication: Elige la autenticación adecuada si es necesario
- Tools to Include: Elige qué herramientas de Tempo exponer al AI Agent
Conecta el nodo MCP Client Tool a un nodo AI Agent que usará las capacidades de consulta de Tempo

Ejemplo de flujo de trabajo: Trigger → MCP Client Tool (servidor de Tempo) → AI Agent (Claude)

Ejemplo de uso

Una vez configurado, puedes usar las herramientas en Claude con consultas como:

"Consulta Tempo para trazas con la consulta {duration>1s}"
"Encuentra trazas del servicio frontend en Tempo usando la consulta {service.name=\"frontend\"}"
"Muéstrame las 50 trazas más recientes de Tempo con {http.status_code=500}"

Licencia

Este proyecto está licenciado bajo la Licencia MIT.