Simple Loki MCP Server

Consulta registros de Grafana Loki usando logcli con una alternativa automática a la API HTTP.

Documentación

Simple Loki MCP Server

Loki MCP Server es una interfaz de Model Context Protocol (MCP) para consultar registros de Grafana Loki usando logcli. El servidor permite a los asistentes de IA acceder y analizar datos de registros de Loki directamente.

Características

Consulta registros de Loki con soporte completo de LogQL
Obtén valores de etiquetas y metadatos
Soporte de autenticación y configuración mediante variables de entorno o archivos de configuración
Proporciona resultados formateados en diferentes formatos de salida (predeterminado, crudo, líneas JSON)
Cambio automático a la API HTTP cuando logcli no está disponible en el entorno

Requisitos previos

Node.js v16 o superior
TypeScript
(Opcional) Grafana Loki logcli instalado y accesible en tu PATH. Si logcli no está disponible, el servidor usará automáticamente la API HTTP de Loki en su lugar
Acceso a una instancia del servidor Loki

Instalación

Instalación mediante Smithery

Para instalar Simple Loki MCP Server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @ghrud92/simple-loki-mcp --client claude

para MCP

{
  "mcpServers": {
    "simple-loki": {
      "command": "npx",
      "args": ["-y", "simple-loki-mcp"],
      "env": {
        "LOKI_ADDR": "https://loki.sup.band"
      }
    }
  }
}

npm

Clona el repositorio:

git clone https://github.com/ghrud92/loki-mcp.git
cd loki-mcp

Instala las dependencias:

npm install

Compila el proyecto:

npm run build

Herramientas MCP disponibles

query-loki

Consulta registros de Loki con opciones de filtrado.

Parámetros:

query (obligatorio): Cadena de consulta de Loki (LogQL)
from: Marca de tiempo de inicio (p. ej., "2023-01-01T12:00:00Z")
to: Marca de tiempo de fin (p. ej., "2023-01-01T13:00:00Z")
limit: Número máximo de registros a devolver
batch: Tamaño de lote para los resultados de la consulta
output: Formato de salida ("default", "raw" o "jsonl")
quiet: Suprimir metadatos de la consulta
forward: Mostrar resultados en orden cronológico

get-label-values

Recupera todos los valores de una etiqueta específica.

Parámetros:

label (obligatorio): Nombre de la etiqueta para obtener sus valores

get-labels

Recupera todas las etiquetas disponibles.

No requiere parámetros.

Configuración

Puedes configurar el acceso a Loki usando:

Variables de entorno

LOKI_ADDR: Dirección del servidor Loki (URL)
LOKI_USERNAME: Nombre de usuario para autenticación básica
LOKI_PASSWORD: Contraseña para autenticación básica
LOKI_TENANT_ID: ID de inquilino para Loki multiinquilino
LOKI_BEARER_TOKEN: Token de portador para autenticación
LOKI_BEARER_TOKEN_FILE: Archivo que contiene el token de portador
LOKI_CA_FILE: Archivo CA personalizado para TLS
LOKI_CERT_FILE: Archivo de certificado de cliente para TLS
LOKI_KEY_FILE: Archivo de clave de cliente para TLS
LOKI_ORG_ID: ID de organización para configuraciones multiorganización
LOKI_TLS_SKIP_VERIFY: Omitir verificación TLS ("true" o "false")
LOKI_CONFIG_PATH: Ruta personalizada al archivo de configuración
DEBUG: Habilitar registro de depuración

Nota: Cuando el cliente usa el modo de API HTTP (cuando logcli no está disponible), se usan los mismos parámetros de configuración para autenticarse y conectarse al servidor Loki.

Archivos de configuración

Alternativamente, crea un archivo logcli-config.yaml en una de estas ubicaciones:

Ruta personalizada especificada por LOKI_CONFIG_PATH
Directorio de trabajo actual
Tu directorio de inicio (~/.logcli-config.yaml)

Ejemplo de archivo de configuración:

addr: https://loki.example.com
username: user
password: pass
tenant_id: mytenant

Uso

Inicia el servidor:

npm start

Para desarrollo:

npm run dev

Detalles de implementación

Cambio automático a la API HTTP

El servidor verificará automáticamente si logcli está instalado y disponible en el entorno:

Si logcli está disponible, se usará para todas las consultas, proporcionando la funcionalidad completa de la herramienta CLI
Si logcli no está disponible, el servidor cambiará automáticamente al uso de la API HTTP de Loki:
- No se necesita configuración adicional
- Se usan los mismos parámetros de autenticación para la API HTTP
- El formato de respuesta es consistente con la salida de la CLI
- Se aplica un límite predeterminado de 1000 registros por consulta en ambos modos

Esta detección automática garantiza que el servidor funcione sin problemas en diferentes entornos sin configuración manual.

Desarrollo

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Run tests
npm run test

Licencia

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