Loki MCP

Servidor Loki MCP

Consulta registros de Grafana Loki directamente desde agentes de IA utilizando el Model Context Protocol (MCP).

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

Admite integración con:

• Claude Desktop
• frameworks de agentes de IA
• herramientas de automatización
• flujos de trabajo 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é hay 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.

Adicionalmente, este servidor aplica validación estricta de entrada (límites máximos, validación de dirección, verificación de formato de nombres de etiquetas, autenticación mutuamente exclusiva) 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 una ventana 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	Obligatoria	Valor 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 implementaciones multi-tenant
LOKI_HTTP_TIMEOUT	no	30s	Tiempo de espera de solicitud HTTP (duración Go, p. ej. 10s, 1m)

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

Uso con Claude Code

Añade a tu 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ñade a tu 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 una ventana de tiempo.

Parámetro	Tipo	Obligatorio	Valor predeterminado	Descripción
query	string	sí	—	Expresión de consulta LogQL
start	string	no	hace 1 hora	Inicio del rango de tiempo (RFC3339 o Unix nano)
end	string	no	ahora	Fin del rango 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	Obligatorio	Valor 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	Obligatorio	Valor predeterminado	Descripción
start	string	no	hace 6 horas	Inicio del rango de tiempo
end	string	no	ahora	Fin del rango de tiempo

label_values

Lista valores para una etiqueta específica.

Parámetro	Tipo	Obligatorio	Valor predeterminado	Descripción
label	string	sí	—	Nombre de la etiqueta
start	string	no	hace 6 horas	Inicio del rango de tiempo
end	string	no	ahora	Fin del rango de tiempo

series

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

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

Stack de Desarrollo Local

Se incluye una configuración de Docker Compose en deploy/ para levantar un entorno completo de Loki 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 te resulta útil, por favor deja una estrella en el repositorio.