Servidor MCP de Loki | Awesome MCP Servers

Loki MCP Server

Una implementación de servidor basada en Go para el Model Context Protocol (MCP) con integración de 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 mediante stdin/stdout y SSE siguiendo el Model Context Protocol (MCP). Esto lo hace adecuado para su uso con Claude Desktop y otros clientes compatibles con MCP.

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 servidor Loki MCP implementa el Model Context Protocol (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 (por defecto: de la variable de entorno LOKI_URL o http://localhost:3100)
- start: Hora de inicio para la consulta (por defecto: hace 1 hora)
- end: Hora de fin para la consulta (por defecto: ahora)
- limit: Número máximo de entradas a devolver (por defecto: 100)
- org: ID de organización para la consulta (enviado como cabecera X-Scope-OrgID)

Variables de entorno

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

LOKI_URL: URL del servidor Loki por defecto a usar si no se especifica en la solicitud
LOKI_ORG_ID: ID de organización por defecto a usar si no se especifica en la solicitud
LOKI_USERNAME: Nombre de usuario por defecto para autenticación básica si no se especifica en la solicitud
LOKI_PASSWORD: Contraseña por defecto para autenticación básica si no se especifica en la solicitud
LOKI_TOKEN: Token de portador por defecto 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 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 de 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 de prueba para probar:

# 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 los registros visualmente.

Soporte de Server-Sent Events (SSE)

El servidor ahora admite dos modos de comunicación:

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

El puerto por defecto 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

Usando Docker con SSE

Al ejecutar 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 servidor Loki MCP con flujos de trabajo de n8n:

Instala el nodo MCP Client Tools 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 adecuada si es necesario
- Herramientas a incluir: Elige qué herramientas de Loki exponer al Agente de IA
Conecta el nodo MCP Client Tool a un nodo de Agente de IA que usará las capacidades de consulta de Loki

Ejemplo de flujo de trabajo: Disparador → MCP Client Tool (servidor Loki) → Agente de IA (Claude)

Arquitectura

El servidor Loki MCP 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 de 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 de 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 ejecuta 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 consulta 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 a la 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 el 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 en lenguaje natural, el asistente de IA mapeará 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 cabecera 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 mapearlos 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 en lenguaje natural sin tener que especificar los detalles de autenticación cada vez.

Uso con Cursor

También puedes integrar el servidor Loki MCP con el editor Cursor. Para hacerlo, 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 obtener más detalles.

Ejecución de pruebas

El proyecto incluye pruebas unitarias exhaustivas 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 ./...

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 de Docker

Pruebas locales con Loki

Soporte de Server-Sent Events (SSE)

Endpoints del servidor

Usando 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 a la organización

Menciones contextuales de organización

Escenarios multi-tenant

Combinado con otros parámetros

Uso con Cursor

Licencia

Ejecución de pruebas