Simple Loki MCP Server

Simple Loki MCP Server

Loki MCP Server es una interfaz del Protocolo de Contexto de Modelo (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)
• Retroceso 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

1. Clona el repositorio:

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

2. Instala las dependencias:

npm install

3. 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 multi-org
• 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

Retroceso automático a la API HTTP

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

1. Si logcli está disponible, se usará para todas las consultas, proporcionando la funcionalidad completa de la herramienta CLI
2. Si logcli no está disponible, el servidor retrocederá 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.