grafana-log-mcp

grafana-log-mcp es una capa genérica y reutilizable de consulta de logs para Grafana/Loki, expuesta como un servidor MCP stdio de solo lectura. Se comunica con la API de Grafana y devuelve logs sin procesar además de vistas agregadas (consultas lentas, huellas de errores y tendencias de volumen), filtradas por ventana de tiempo, proyecto, palabra clave o umbral de duración.

No incluye ninguna lógica de negocio ni heurística específica. Una vez que los logs están disponibles, correlacionarlos con el código fuente y explicar por qué ocurrió algo queda en manos de tu IDE de IA y de las skills/reglas del proyecto de negocio que se esté depurando; el servidor solo pone los datos a disposición.

Posicionamiento en español: es una capa genérica de consulta de logs (solo obtiene, agrega y devuelve logs, reutilizable entre proyectos, sin lógica de negocio ni atribución de causas); el análisis de la causa concreta lo realiza la IA del llamante combinando el código fuente del proyecto de negocio y las skills/experiencia del propio proyecto.

Instalación

# 方式一：npm 全局安装（推荐）
npm install -g grafana-log-mcp

Tras la instalación global se proporcionan dos comandos: grafana-log-mcp (inicia el servidor MCP) y grafana-log-mcp-login (inicio de sesión interactivo).

También puedes ejecutarlo sin instalar, en una sola vez con npx: npx -y grafana-log-mcp / npx -y grafana-log-mcp-login.

Related MCP server: grafana-mcp

Inicio rápido

npm ya instalado (consumidor)

# 1. 登录（交互输入 Grafana 地址与用户名密码，写入 ~/.grafana-log-mcp/credentials.json，0600）
grafana-log-mcp-login

# 2. 校验凭证（排查"MCP 突然查不了"）
grafana-log-mcp-login --check

# 3. 启动 MCP Server（stdio）
grafana-log-mcp

Desarrollo desde el código fuente (tras clonar el repositorio)

# 1. 安装依赖（node >= 18）
npm install

# 2. 登录
node bin/login.js

# 3. 校验凭证
node bin/login.js --check

# 4. 启动 MCP Server（stdio）
npm start          # 即 node src/index.js

Integración con IDE de IA (Trae/Claude, etc.)

Añádelo en la configuración de MCP (según el formato de configuración de cada IDE):

{
  "mcpServers": {
    "grafana-log": {
      "command": "npx",
      "args": ["-y", "grafana-log-mcp"],
      "env": { "GRAFANA_URL": "https://your-grafana.example.com" }
    }
  }
}

Se recomienda habilitarlo globalmente: al solucionar problemas se abre el repositorio de código fuente del proyecto de negocio; si añades la configuración de MCP como global, podrás directamente "preguntar → consultar logs → leer código → dar la causa" en cualquier repositorio.

Herramientas (15)

Tres límites duros de volumen de datos: limit ≤ 1000, 500 caracteres por línea, respuesta de 25 000 caracteres (si se supera, se conservan el inicio y el final y se omite el medio, con la correspondiente anotación). Si una línea se trunca, se puede usar get_full_line con el time de esa línea para recuperar el contenido completo.

Registro de proyectos (projects.json)

El archivo de registro se localiza según la siguiente prioridad (summary.configFile devuelto por list_projects muestra la ubicación real actualmente activa):

1. El archivo especificado por la variable de entorno GRAFANA_CONFIG_PATH

2. config/projects.json dentro del paquete (en el repositorio de código fuente)

3. ~/.grafana-log-mcp/projects.json (en el mismo directorio que las credenciales, ubicación predeterminada tras la instalación con npm)

Consulta config/projects.example.json para ver el formato de referencia; cada elemento incluye key / datasourceUid / labels{app,group} / aliases(alias en chino) / repoPath. repoPath es solo para que el IDE de IA localice el código; el propio MCP no lee el código fuente. La base de conocimiento de fallos está en config/failure-patterns.json; cuando encuentres un nuevo tipo de fallo, solo tienes que añadir una entrada.

Variables de entorno (opcional)

GRAFANA_URL=                  # Grafana 地址：作为 grafana-log-mcp-login 的默认地址，并覆盖凭证文件中的地址
GRAFANA_ORG_ID=1              # 可选：仅影响 build_explore_url 生成的 Explore 深链的 orgId 参数（默认 1）；不参与实际日志查询
GRAFANA_CREDENTIALS_PATH=     # 自定义凭证文件位置
GRAFANA_CONFIG_PATH=          # 自定义项目登记文件（projects.json）位置
GRAFANA_MOCK=1                # 本地 mock 模式：不连真实 Grafana、无需登录（2500 条合成日志，验证翻页/截断/慢日志）

Nota: el MCP no incorpora ninguna dirección predeterminada de Grafana ni configuración de proyecto (es genérico); la dirección proviene de la introducida al iniciar sesión (archivo de credenciales) o de la variable de entorno GRAFANA_URL; la configuración específica de la instancia (registro de proyectos, uid de la fuente de datos) se mantiene en projects.json (consulta las reglas de localización de la sección anterior).

Pruebas

node test/unit.mjs         # 纯逻辑单测（合成日志，无网络依赖）：59 通过
node test/integration.mjs  # 编排器端到端（mock client + 独立 fixture 配置）：20 通过