Servidor MCP de Loki | Awesome MCP Servers

Loki MCP Server

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

Comenzando

Requisitos previos

Go 1.16 o superior

Compilación y ejecución

Compila y ejecuta el servidor:

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

# Run the server
./loki-mcp-server

O ejecuta directamente con Go:

go run ./cmd/server

El servidor se comunica usando stdin/stdout siguiendo el Protocolo de Contexto de Modelo (MCP). Esto lo hace adecuado para su uso con Claude Desktop y otros clientes compatibles con MCP. No se ejecuta como un servidor HTTP en un puerto.

Estructura del proyecto

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

Servidor MCP

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

Herramienta de consulta Loki

La herramienta loki_query te permite consultar datos de registros de Grafana Loki:

Parámetros requeridos:
- query: Cadena de consulta LogQL
Parámetros opcionales:
- url: La URL del servidor Loki (predeterminado: de la variable de entorno LOKI_URL o http://localhost:3100)
- 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 entradas a devolver (predeterminado: 100)
- org: ID de organización para la consulta (enviado como encabezado X-Scope-OrgID)

Variables de entorno

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

LOKI_URL: URL del servidor Loki predeterminada para usar si no se especifica en la solicitud
LOKI_ORG_ID: ID de organización predeterminado para usar si no se especifica en la solicitud
LOKI_USERNAME: Nombre de usuario predeterminado para autenticación básica si no se especifica en la solicitud
LOKI_PASSWORD: Contraseña predeterminada para autenticación básica si no se especifica en la solicitud
LOKI_TOKEN: Token de portador predeterminado para autenticación si no se especifica en la solicitud

Nota de seguridad: Al usar variables de entorno de autenticación, ten cuidado de no exponer credenciales sensibles en registros o archivos de configuración. Considera usar autenticación basada en tokens en lugar de nombre de usuario/contraseña cuando sea posible.

Probando el servidor MCP

Puedes probar el servidor MCP usando el cliente proporcionado:

# Build the client
go build -o loki-mcp-client ./cmd/client

# Loki query examples:
./loki-mcp-client loki_query "{job=\"varlogs\"}"
./loki-mcp-client loki_query "{job=\"varlogs\"}" "-1h" "now" 100

# Using environment variables:
export LOKI_URL="http://localhost:3100"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables for both URL and org:
export LOKI_URL="http://localhost:3100"
export LOKI_ORG_ID="tenant-123"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables for authentication:
export LOKI_URL="http://localhost:3100"
export LOKI_USERNAME="admin"
export LOKI_PASSWORD="password"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables with bearer token:
export LOKI_URL="http://localhost:3100"
export LOKI_TOKEN="your-bearer-token"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using all environment variables together:
export LOKI_URL="http://localhost:3100"
export LOKI_ORG_ID="tenant-123"
export LOKI_USERNAME="admin"
export LOKI_PASSWORD="password"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using org parameter for multi-tenant setups:
./loki-mcp-client loki_query "{job=\"varlogs\"}" "" "" "" "" "" "tenant-123"

Soporte Docker

Puedes compilar y ejecutar el servidor MCP usando Docker:

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

# Run the server
docker run --rm -i loki-mcp-server

Alternativamente, puedes usar Docker Compose:

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

Pruebas locales con Loki

El proyecto incluye una configuración completa de Docker Compose para probar consultas de Loki localmente:

Inicia el entorno de Docker Compose:
```
docker-compose up -d
```
Esto iniciará:
- Un servidor Loki en el puerto 3100
- Una instancia de Grafana en el puerto 3000 (preconfigurada con Loki como fuente de datos)
- Un contenedor generador de registros que envía registros de muestra a Loki
- El servidor Loki MCP

Usa el script de prueba proporcionado para consultar registros:

# Run with default parameters (queries last 15 minutes of logs)
./test-loki-query.sh

# Query for error logs
./test-loki-query.sh '{job="varlogs"} |= "ERROR"'

# Specify a custom time range and limit
./test-loki-query.sh '{job="varlogs"}' '-1h' 'now' 50

Inserta registros ficticios para pruebas:

# Insert 10 dummy logs with default settings
./insert-loki-logs.sh

# Insert 20 logs with custom job and app name
./insert-loki-logs.sh --num 20 --job "custom-job" --app "my-app"

# Insert logs with custom environment and interval
./insert-loki-logs.sh --env "production" --interval 0.5

# Show help message
./insert-loki-logs.sh --help

Accede a la interfaz de Grafana en http://localhost:3000 para explorar registros visualmente.

Soporte de Eventos Enviados por el Servidor (SSE)

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 Eventos Enviados por el Servidor (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

Uso de Docker con SSE

Cuando ejecutes el servidor con Docker, asegúrate de exponer el puerto 8080:

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

# Run the server with port mapping
docker run -p 8080:8080 --rm -i loki-mcp-server

Integración con n8n

Puedes integrar el Loki MCP Server con flujos de trabajo de n8n:

Instala el nodo de Herramientas del Cliente MCP en n8n
Configura el nodo con estos parámetros:
- Endpoint SSE: http://your-server-address:8080/sse (reemplaza con la dirección real de tu servidor)
- Autenticación: Elige la autenticación apropiada si es necesaria
- Herramientas a incluir: Elige qué herramientas de Loki exponer al Agente de IA
Conecta el nodo de Herramienta del Cliente MCP a un nodo de Agente de IA que usará las capacidades de consulta de Loki

Ejemplo de flujo de trabajo: Disparador → Herramienta del Cliente MCP (servidor Loki) → Agente de IA (Claude)

Arquitectura

El Loki MCP Server usa una arquitectura modular:

Servidor: La implementación principal del servidor MCP en cmd/server/main.go
Cliente: Un cliente de prueba en cmd/client/main.go para interactuar con el servidor MCP
Manejadores: Manejadores de herramientas individuales en internal/handlers/
- loki.go: Funcionalidad de consulta de Grafana Loki

Uso con Claude Desktop

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

Opción 1: Usando el binario compilado

Compila el servidor:

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

Agrega la configuración a tu archivo de configuración de Claude Desktop usando claude_desktop_config_binary.json.

Opción 2: Usando Go Run con un script de shell

Haz ejecutable el script:

chmod +x run-mcp-server.sh

Agrega la configuración a tu archivo de configuración de Claude Desktop usando claude_desktop_config_script.json.

Opción 3: Usando Docker (Recomendado)

Compila la imagen Docker:

docker build -t loki-mcp-server .

Agrega la configuración a tu archivo de configuración de Claude Desktop usando claude_desktop_config_docker.json.

Detalles de configuración

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

Puedes usar una de las configuraciones de ejemplo proporcionadas en este repositorio:

claude_desktop_config.json: Plantilla genérica
claude_desktop_config_example.json: Ejemplo usando go run con la ruta actual
claude_desktop_config_binary.json: Ejemplo usando el binario compilado
claude_desktop_config_script.json: Ejemplo usando un script de shell (recomendado para go run)
claude_desktop_config_docker.json: Ejemplo usando Docker (más confiable)

Notas:

Al usar go run con Claude Desktop, es posible que necesites configurar varias variables de entorno tanto en el script como en el archivo de configuración:
- HOME: El directorio de inicio del usuario
- GOPATH: El directorio del espacio de trabajo de Go
- GOMODCACHE: El directorio de caché de módulos de Go
- GOCACHE: El directorio de caché de compilación de Go
Estos son necesarios para asegurar que Go pueda encontrar sus módulos y caché de compilación cuando se ejecute desde Claude Desktop.
Usar Docker es el enfoque más confiable ya que empaqueta todas las dependencias y variables de entorno en un contenedor.

O crea tu propia configuración:

{
  "mcpServers": {
    "lokiserver": {
      "command": "path/to/loki-mcp-server",
      "args": [],
      "env": {
        "LOKI_URL": "http://localhost:3100",
        "LOKI_ORG_ID": "your-default-org-id",
        "LOKI_USERNAME": "your-username",
        "LOKI_PASSWORD": "your-password",
        "LOKI_TOKEN": "your-bearer-token"
      },
      "disabled": false,
      "autoApprove": ["loki_query"]
    }
  }
}

Asegúrate de reemplazar path/to/loki-mcp-server con la ruta absoluta al binario compilado o al código fuente.

Reinicia Claude Desktop.
Ahora puedes usar las herramientas en Claude:
- Ejemplos de consultas de Loki:
  - "Consulta Loki para registros con la consulta {job="varlogs"}"
  - "Encuentra registros de error de la última hora en Loki usando la consulta {job="varlogs"} |= "ERROR""
  - "Muéstrame los 50 registros más recientes de Loki con job=varlogs"
  - "Consulta Loki para registros con org 'tenant-123' usando la consulta {job="varlogs"}"

Uso del ID de organización en indicaciones de lenguaje natural

Al usar este servidor MCP con Claude Desktop u otros asistentes de IA, los usuarios pueden mencionar naturalmente el ID de organización en sus indicaciones de varias maneras:

Referencia directa de organización

"Consulta Loki para registros de la organización 'tenant-123' con la consulta {job="varlogs"}"
"Busca registros de Loki para org 'production-env' usando {job="web"}"
"Obtén registros del ID de organización 'client-abc' que coincidan con {service="api"}"

Menciones contextuales de organización

"Revisa los registros de error de nuestro tenant de producción (org: prod-001) usando la consulta {level="error"}"
"Encuentra todos los registros de la organización de cliente 'customer-xyz' de la última hora"
"Consulta Loki con org tenant-456 para encontrar registros que coincidan con {job="backend"}"

Escenarios multi-tenant

"Cambia a la organización 'dev-team' y consulta {job="logs"} para depuración"
"Usa org 'staging-env' para buscar registros de advertencia en las últimas 2 horas"
"Busca registros en tenant 'qa-environment' para cualquier mensaje de error"

Combinado con otros parámetros

"Consulta Loki para la organización 'prod-cluster' desde hace 2 horas hasta ahora con límite 50"
"Obtén los últimos 100 registros de org 'microservice-team' para la consulta {app="payment"}"

Cuando menciones cualquiera de estas indicaciones de lenguaje natural, el asistente de IA asignará automáticamente términos como "organización", "org", "tenant" o "ID de organización" al parámetro org en la herramienta de consulta de Loki, que se envía como el encabezado X-Scope-OrgID a tu servidor Loki para un filtrado multi-tenant adecuado.

La clave es mencionar naturalmente cualquier parámetro específico en tu solicitud: la IA entenderá cómo asignarlos a los parámetros apropiados de la herramienta de consulta de Loki. Cuando los parámetros no se mencionan explícitamente, el sistema usará automáticamente los valores predeterminados de las variables de entorno:

LOKI_URL para la URL del servidor Loki
LOKI_ORG_ID para el ID de organización
LOKI_USERNAME y LOKI_PASSWORD para autenticación básica
LOKI_TOKEN para autenticación con token de portador

Esto hace que sea muy conveniente configurar los parámetros de conexión predeterminados una vez y luego usar consultas de lenguaje natural sin tener que especificar detalles de autenticación cada vez.

Uso con Cursor

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

Configuración de Docker:

{
  "mcpServers": {
    "loki-mcp-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "LOKI_URL=http://host.docker.internal:3100", 
               "-e", "LOKI_ORG_ID=your-default-org-id",
               "-e", "LOKI_USERNAME=your-username",
               "-e", "LOKI_PASSWORD=your-password",
               "-e", "LOKI_TOKEN=your-bearer-token",
               "loki-mcp-server:latest"]
    }
  }
}

Después de agregar esta configuración, reinicia Cursor y podrás usar la herramienta de consulta de Loki directamente dentro del editor.

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para más detalles.

Ejecución de pruebas

El proyecto incluye pruebas unitarias integrales y flujos de trabajo de CI/CD para garantizar la confiabilidad:

# Run all tests
go test ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# Run tests with race detection  
go test -race ./...

Corrección de error de marca de tiempo (Problema #3)

Este proyecto anteriormente tenía un error crítico donde las marcas de tiempo se mostraban como año 2262 en lugar de fechas correctas. Esto se ha corregido y hay pruebas de regresión implementadas:

Causa raíz: Loki devuelve marcas de tiempo en nanosegundos, pero el código las trataba incorrectamente como segundos y las multiplicaba por 1,000,000,000
Corrección: Manejar correctamente las marcas de tiempo en nanosegundos de Loki
Pruebas: Pruebas integrales aseguran que las marcas de tiempo se muestren correctamente (por ejemplo, 2024, 2023) en lugar de 2262
Protección de CI: Pruebas automatizadas previenen la regresión de este error crítico

Las pruebas verifican específicamente:

✅ Las marcas de tiempo muestran años correctos en lugar de 2262
✅ Múltiples formatos de marca de tiempo funcionan correctamente
✅ Las marcas de tiempo inválidas tienen un comportamiento de respaldo adecuado
✅ Integración con instancias reales de Loki

Loki MCP Server

Documentación

Loki MCP Server

Comenzando

Requisitos previos

Compilación y ejecución

Estructura del proyecto

Servidor MCP

Herramienta de consulta Loki

Variables de entorno

Probando el servidor MCP

Soporte Docker

Pruebas locales con Loki

Soporte de Eventos Enviados por el Servidor (SSE)

Endpoints del servidor

Uso de Docker con SSE

Integración con n8n

Arquitectura

Uso con Claude Desktop

Opción 1: Usando el binario compilado

Opción 2: Usando Go Run con un script de shell

Opción 3: Usando Docker (Recomendado)

Detalles de configuración

Uso del ID de organización en indicaciones de lenguaje natural

Referencia directa de organización

Menciones contextuales de organización

Escenarios multi-tenant

Combinado con otros parámetros

Uso con Cursor

Licencia

Ejecución de pruebas

Corrección de error de marca de tiempo (Problema #3)