Loki MCP

Depura e investiga problemas de aplicaciones usando IA y Grafana Loki

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor Loki MCP

Stars

Consulta registros de Grafana Loki directamente desde agentes de IA usando el Protocolo de Contexto de Modelo (MCP).

Construido en Go. Permite análisis de registros impulsado por IA usando LogQL.

Soporta integración con:

Claude Desktop
Frameworks de agentes de IA
Herramientas de automatización
Flujos de trabajo de DevOps

Motivación

El grafana/loki-mcp oficial expone una única herramienta loki_query, lo que significa que el LLM ya debe conocer nombres y valores de etiquetas válidos antes de poder construir una consulta. Este proyecto adopta un enfoque diferente al proporcionar 5 herramientas granulares — labels, label_values y series permiten que el LLM descubra primero qué está disponible en Loki, y luego construya llamadas precisas de query_range o query. El resultado es una recuperación de registros más precisa con menos idas y vueltas desperdiciadas.

Además, este servidor aplica validación estricta de entrada (límites máximos, validación de dirección, comprobaciones de formato de nombres de etiquetas, autenticación mutuamente excluyente) para detectar errores tempranamente en lugar de reenviar solicitudes incorrectas a Loki.

Características

query_range — Ejecuta consultas de rango LogQL para obtener registros en un intervalo de tiempo
query — Ejecuta consultas instantáneas LogQL para evaluación en un punto en el tiempo
labels — Lista todos los nombres de etiquetas disponibles
label_values — Lista valores para una etiqueta específica
series — Encuentra series de flujos de registros activos que coincidan con un selector

Instalación

Homebrew

brew install incu6us/tap/loki-mcp-server

Instalación con Go

go install github.com/incu6us/loki-mcp-server/cmd/loki-mcp-server@latest

O compilar desde el código fuente:

git clone https://github.com/incu6us/loki-mcp-server.git
cd loki-mcp
go build -o loki-mcp-server ./cmd/loki-mcp-server

Configuración

El servidor se configura completamente mediante variables de entorno, inyectadas por el cliente MCP.

Variable	Requerida	Predeterminado	Descripción
`LOKI_URL`	sí	—	URL base de la instancia de Loki
`LOKI_USERNAME`	no	—	Nombre de usuario de autenticación básica
`LOKI_PASSWORD`	no	—	Contraseña de autenticación básica
`LOKI_BEARER_TOKEN`	no	—	Autenticación con token Bearer
`LOKI_TLS_SKIP_VERIFY`	no	`false`	Omitir verificación de certificado TLS
`LOKI_TENANT_ID`	no	—	Cabecera `X-Scope-OrgID` para despliegues multiinquilino
`LOKI_HTTP_TIMEOUT`	no	`30s`	Tiempo de espera de solicitudes HTTP (duración Go, p. ej. `10s`, `1m`)
`MCP_HTTP_ADDR`	no	—	Dirección de escucha para el transporte HTTP transmisible, p. ej. `:8080`. Sin definir significa stdio

Nota: La autenticación básica (LOKI_USERNAME/LOKI_PASSWORD) y el token Bearer (LOKI_BEARER_TOKEN) son mutuamente excluyentes.

Transportes

Por defecto, el servidor habla MCP sobre stdio, que es lo que esperan Claude Code, Claude Desktop y la mayoría de los clientes locales.

Establezca MCP_HTTP_ADDR para servir el transporte HTTP transmisible en su lugar, para ejecutar el servidor como un endpoint remoto detrás de un proxy o puerta de enlace:

LOKI_URL=http://loki:3100 MCP_HTTP_ADDR=:8080 loki-mcp-server
# MCP endpoint: http://localhost:8080/mcp

El modo HTTP no tiene estado, por lo que puede ejecutarse detrás de un balanceador de carga con varias réplicas. No lleva autenticación propia — colóquelo detrás de TLS y un proxy autenticador antes de exponerlo, y recuerde que quien alcance el endpoint puede leer cada línea de registro que las credenciales configuradas de LOKI_URL puedan ver.

Uso con Claude Code

Añada a su configuración MCP de Claude Code (~/.claude.json):

{
  "mcpServers": {
    "loki-mcp-server": {
      "type": "stdio",
      "command": "/path/to/loki-mcp-server",
      "args": [],
      "env": {
        "LOKI_URL": "http://loki:3100",
        "LOKI_USERNAME": "admin",
        "LOKI_PASSWORD": "secret"
      }
    }
  }
}

Uso con Claude Desktop

Añada a su configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "loki-mcp-server": {
      "type": "stdio",
      "command": "/path/to/loki-mcp-server",
      "args": [],
      "env": {
        "LOKI_URL": "http://loki:3100",
        "LOKI_USERNAME": "admin",
        "LOKI_PASSWORD": "secret"
      }
    }
  }
}

Herramientas

query_range

Ejecuta una consulta de rango LogQL contra Loki para obtener registros en un intervalo de tiempo.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`query`	string	sí	—	Expresión de consulta LogQL
`start`	string	no	hace 1 hora	Inicio del intervalo de tiempo (RFC3339 o Unix nano)
`end`	string	no	ahora	Fin del intervalo de tiempo
`limit`	number	no	100	Máximo de entradas (máx. 5000)
`direction`	string	no	backward	`forward` o `backward`

query

Ejecuta una consulta instantánea LogQL para evaluación en un punto en el tiempo.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`query`	string	sí	—	Expresión de consulta LogQL
`limit`	number	no	100	Máximo de entradas (máx. 5000)
`time`	string	no	ahora	Marca de tiempo de evaluación
`direction`	string	no	backward	`forward` o `backward`

labels

Lista todos los nombres de etiquetas disponibles en Loki.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`start`	string	no	hace 6 horas	Inicio del intervalo de tiempo
`end`	string	no	ahora	Fin del intervalo de tiempo

label_values

Lista valores para una etiqueta específica.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`label`	string	sí	—	Nombre de la etiqueta
`start`	string	no	hace 6 horas	Inicio del intervalo de tiempo
`end`	string	no	ahora	Fin del intervalo de tiempo

series

Encuentra series de flujos de registros activos que coincidan con un selector.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`match`	string	sí	—	Selector de flujo (p. ej. `{app="nginx"}`)
`start`	string	no	hace 6 horas	Inicio del intervalo de tiempo
`end`	string	no	ahora	Fin del intervalo de tiempo

Pila de Desarrollo Local

Se incluye una configuración de Docker Compose en deploy/ para levantar un entorno Loki completo para pruebas:

Loki — almacenamiento de registros en http://localhost:3100
Grafana — interfaz de usuario en http://localhost:3000 (admin anónimo, Loki preconfigurado como fuente de datos)
Promtail — recopila registros de contenedores y los envía a Loki
Generador de registros — emite registros JSON estructurados con aplicaciones aleatorias (nginx, api, gateway, auth, payments), niveles y mensajes

# Start the stack
docker compose -f deploy/docker-compose.yml up -d

# Use loki-mcp-server against local Loki
LOKI_URL=http://localhost:3100 loki-mcp-server

# Stop the stack
docker compose -f deploy/docker-compose.yml down

Desarrollo

# Run tests
go test ./...

# Build
go build -o loki-mcp-server ./cmd/loki-mcp-server

# Vet
go vet ./...

⭐ Si este proyecto le resulta útil, por favor dé una estrella al repositorio.