loki-mcp-server

Servidor MCP Loki

Un servidor MCP stdio local para leer Grafana Loki con un agente. Expone cinco herramientas de texto y es compatible con Loki 2.6.1 y 3.x. Loki en sí es de solo lectura; la única escritura es un archivo local exportLogs.

Cada herramienta de datos requiere una conexión explícita. queryLogs, countLogs y exportLogs requieren una consulta de logs LogQL, como {app="backend"} |= "ERROR". Usa discoverLogs para encontrar nombres de etiquetas, valores y combinaciones reales en los conjuntos de etiquetas de flujo. El servidor solo construye la expresión count_over_time para countLogs; no infiere filtros ni interpreta causas. Las respuestas de las herramientas son texto legible sin un esquema de salida.

Compilar y ejecutar

Se requiere JDK 21 o superior; el proyecto usa un toolchain de Java 21 y el wrapper de Gradle.

.\gradlew.bat bootJar
java -jar build/libs/loki-mcp-server.jar

En Linux/macOS usa ./gradlew. El proceso espera MCP JSON-RPC en stdin. stdout está reservado para JSON-RPC; los diagnósticos van a stderr y a ~/.loki-mcp-server/logs/loki-mcp-server.log.

Un loki-mcp-server.jar precompilado está adjunto a cada release, por lo que compilar es opcional.

Para Claude Code, registrar el jar es un solo comando:

claude mcp add --scope user loki -- java -jar /path/to/loki-mcp-server.jar

Docker

La imagen se publica en GHCR con cada release. Monta el directorio que contiene connections.json en /data; el servidor también escribe sus logs y exportaciones predeterminadas allí:

docker run -i --rm -v ~/.loki-mcp-server:/data ghcr.io/igorolv/loki-mcp-server:latest

El mismo comando es el que un cliente MCP debe lanzar; -i mantiene stdin abierto para el transporte stdio. Las URLs de Loki en connections.json deben ser alcanzables desde dentro del contenedor: usa el nombre de host de Loki en lugar de localhost, o agrega --network host en Linux. Un directorio exportLogs fuera de /data es una ruta dentro del contenedor, así que móntalo también. Para compilar la imagen localmente: docker build -t loki-mcp-server .

Conexiones

El servidor lee ~/.loki-mcp-server/connections.json, o la ruta en LOKI_MCP_CONNECTIONS_FILE. Un archivo mínimo:

{
  "connections": {
    "dev": {
      "description": "Development",
      "hint": "Start with {app=\"backend\"}; inspect app values with discoverLogs.",
      "url": "http://localhost:3100",
      "timezone": "Europe/Moscow",
      "serviceLabels": ["app", "container"]
    }
  }
}

El ejemplo completo usa variables de entorno para URLs no locales. hint le da al modelo sugerencias específicas de la conexión y consejos de campos. serviceLabels nombra las etiquetas utilizadas para mostrar un servicio en líneas compactas. El opcional formatFile nombra un archivo JSON con perfiles JSON, patrones de línea simple y un framePattern opcional; consulta log-formats.json. El opcional exportFormat establece la plantilla predeterminada para exportLogs cuando la llamada a la herramienta omite format. El archivo de conexión puede establecer exportRoots para restringir los destinos de exportación, y límites por conexión. La autenticación y los encabezados de tenant se configuran por conexión; las URLs y credenciales nunca aparecen en las respuestas de las herramientas ni en los diagnósticos. El formato completo está en docs/connections.md.

El servidor carga la configuración estrictamente al inicio sin sondear Loki. Un campo desconocido, una clave duplicada, una variable de entorno faltante o un archivo de formato inválido detienen el inicio con un error de configuración seguro. Los cambios requieren un reinicio.

Uso de las herramientas

1. Llama a listConnections, elige una conexión y usa sus ventanas de tiempo mostradas, el límite de líneas de queryLogs y el tiempo de espera de solicitud para planificar las llamadas.
2. Llama a discoverLogs(connection="dev") para nombres de etiquetas, luego discoverLogs(connection="dev", label="app") para valores. Cuando las combinaciones importan, usa discoverLogs(connection="dev", match="{app="backend"}") para conjuntos completos de etiquetas de flujo o agrega label="namespace" para valores de namespace entre esos conjuntos. Mantén match y su ventana estrechos; estas son etiquetas de flujo, no conteos de líneas de logs. Amplía la ventana en una conexión tranquila cuando sea apropiado.
3. Usa una consulta de logs LogQL con countLogs para verificar el volumen y queryLogs para leer líneas. Por ejemplo, {app="backend"} |= "ERROR"; groupBy="time", step="1d" da intervalos de 24 horas alineados a UTC, y groupBy="app,time" da conteos por app y tiempo. Una captura | regexp nombrada puede proporcionar una etiqueta groupBy. Los marcadores de fecha distinguen intervalos a través de la medianoche.
4. Reduce la consulta cuando una página esté concurrida. queryLogs usa por defecto la página más nueva; order="oldest" comienza al inicio de la ventana. Su pie de página da un final para líneas más antiguas o un inicio para más nuevas. Las líneas límite pueden repetirse, y una marca de tiempo que contenga más líneas de las que caben en una página necesita una consulta más estrecha.
5. Llama a exportLogs cuando el usuario pida un archivo. Pasa el destino del usuario como directorio, como C:\tmp\logs, u omítelo para el directorio de exportación predeterminado. Omitir format usa la plantilla exportFormat configurada de la conexión, si el operador la estableció, y raw en caso contrario. format="raw" escribe las líneas devueltas por Loki, incluyendo cualquier transformación | line_format en la consulta; format="{time} {level} {service} {message}" renderiza localmente. La respuesta da la ruta, los conteos y el formato efectivo, no el contenido de los logs.

queryLogs imprime cualquiera de los extremos de la ventana en orden cronológico. Su vista predeterminada acorta mensajes y trazas de pila para ahorrar tokens del modelo. Un framePattern opcional en el formatFile de la conexión pliega líneas de marco adyacentes independientes en la vista compacta. raw=true muestra cada línea devuelta con etiquetas de flujo y hasta 4000 puntos de código; es una previsualización. Para líneas completas usa exportLogs. La exportación lee hacia adelante en páginas y nunca sobrescribe un archivo existente. Si más líneas comparten un nanosegundo de las que Loki devolverá en una página, la exportación informa que algunas pueden faltar.

La ventana de tiempo predeterminada es now-1h a now. Los tiempos aceptados incluyen now-15m, RFC3339 con desplazamiento, hora local en la zona horaria de la conexión y nanosegundos de época. queryLogs y exportLogs permiten un día por defecto. countLogs permite un día para totales, agrupación por etiqueta o agrupación combinada de etiqueta/tiempo, y siete días para intervalos solo de tiempo; discoverLogs permite siete días sin match y un día con match. Una solicitud a Loki tiene un tiempo de espera de 30 segundos por defecto, y queryLogs permite como máximo 1000 líneas por página por defecto. listConnections muestra los valores efectivos para cada conexión. La exportación se detiene después de 25 segundos por defecto e informa un archivo parcial con una continuación si ha escrito líneas. Después de un tiempo de espera de conteo, reintenta una subventana de un día o una consulta más estrecha. Los límites se pueden establecer por conexión; consulta docs/queries.md y docs/discovery.md.

Configuración del cliente MCP

Claude Code:

claude mcp add --scope user loki -e LOKI_MCP_CONNECTIONS_FILE=C:/path/connections.json -- java -jar C:/path/loki-mcp-server.jar

Codex (~/.codex/config.toml):

[mcp_servers.loki]
command = "java"
args = ["-jar", "C:/path/loki-mcp-server.jar"]
env = { LOKI_MCP_CONNECTIONS_FILE = "C:/path/connections.json" }

Otros clientes pueden lanzar el jar sobre stdio. Mantén stderr separado de stdout.

Errores y diagnósticos

Las fallas de las herramientas son texto Error : con isError=true; Spring AI actualmente repite el texto en una segunda línea. Los argumentos faltantes o mal escritos son respondidos por la validación de entrada del SDK de MCP. Un error de análisis LogQL HTTP 400 de Loki se devuelve para que el modelo pueda corregir su consulta. Otros cuerpos de respuesta ascendentes, URLs, credenciales, tenant y líneas de logs completas se mantienen fuera de las respuestas y diagnósticos. Un 404 se aplica al endpoint llamado, no a toda la conexión. Los detalles del transporte están en docs/http-client.md.

.\gradlew.bat build
.\gradlew.bat integrationTest --console=plain
python scripts/live_smoke/run_smoke.py --connection dev