Skip to main content
Glama
grafana-log-mcp

grafana-log-mcp

by sunshinerich

grafana-log-mcp

npm version npm downloads license Node.js GitHub

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: quickwit-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)

Capa

Herramienta

Uso

Descubrimiento

list_datasources / list_projects

Enumeración de múltiples fuentes de datos, descubrimiento de proyectos (incluidas apps/grupos no registrados)

Metadatos

list_labels / list_label_values

Etiquetas y sus valores

Consulta

query_logs

Logs sin procesar (prioriza requestId + ventana de tiempo estrecha para controlar el volumen de datos)

Consulta

get_full_line

Recupera el texto completo de una sola línea de log (cuando se trunca a 500 caracteres por línea, consulta usando el time de esa línea como timestamp)

Consulta

query_slow_logs

Captura logs lentos según el umbral de duración (p. ej., SQL lentos >30s), empareja y recupera automáticamente el texto de la sentencia SQL; si supera los 30 aciertos (tareas en bucle), agrega automáticamente por operación

Con errores

summarize_errors / logs_volume / trace_context

Clasificación y jerarquización de errores, picos de volumen, trazado de una sola solicitud

Sin errores

compare_baseline / inspect_fields / trace_flow

Plantillas de logs desaparecidas, campos con valores nulos, puntos de interrupción del flujo

Orquestación

diagnose_issue

Primera opción para solucionar problemas: un solo informe de diagnóstico + codeHints

Utilidades

build_explore_url

Genera un enlace profundo a Grafana Explore para verificación manual

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 通过

Available Tools

15 tools
build_explore_urlC

生成 Grafana Explore 深链:AI 给出结论后,人可一键跳到 Grafana 亲自核对原始日志。

Inputs: end, level, range, start, +5 more.

compare_baselineA

与基线窗对比("日志都正常但结果不对"时的首选):找出消失的日志模板(静默跳过信号)、新出现的模板、数值偏离(逻辑 bug 信号)、字段取值分布突变。默认对比前一天同时段。

Inputs: end, range, start, labels, +4 more.

diagnose_issueA

【排障首选】一次调用完成完整根因分析:量级趋势→异常定位→双路径探测(错误突增归并分类 + 无报错基线对比/空值探测/流程断点)→候选原因打分。返回带证据链的诊断报告 + codeHints(供在当前代码仓库中检索定位)。不传 project 则跨全部数据源扫描找疑似源头。

Inputs: end, range, start, project, +2 more.

get_full_lineA

取回日志完整原始行(不做单行截断):query_logs/trace_context 返回的行带"(截断 N 字符)"标记时,把该行的 time 作为 timestamp(配合 keyword)调本工具取回完整内容。

Inputs: end, start, labels, keyword, +5 more.

inspect_fieldsA

字段取值与空值探测("变量没设置"时的首选):统计字段空值率、命中"使用默认值/未配置/fallback"的日志样本。

Inputs: end, range, start, fields, +4 more.

list_datasourcesA

列出该 Grafana 实例上全部 Loki 日志数据源(uid/名称/是否默认),以及各数据源已登记的项目数。多数据源环境下先用它确认要查哪个数据源。

Inputs: no named parameters.

list_labelsB

列出某数据源(或某项目)在时间窗内可用的日志标签名(如 app/group/host/level)。

Inputs: range, labels, project, datasourceUid.

list_label_valuesC

列出指定标签在时间窗内的全部取值(如 labelName=app 列出所有服务名)。

Inputs: labelName (required), range, labels, project, +1 more.

list_projectsA

列出全部可查项目:已登记项目(含中文别名)+ 遍历各 Loki 数据源实时发现的 app/group 组合(默认查最近 24h,标注归属数据源与登记状态)。不知道项目叫什么时先调这个。

Inputs: no named parameters.

logs_volumeC

日志量级趋势与突增检测:分桶计数 + 相对基线的突增倍数 + 异常起始时刻。回答"什么时候开始出问题"。

Inputs: end, range, start, labels, +4 more.

query_logsA

查询原始日志。数据量控制:优先用 requestId 精确到单次请求;配合窄时间窗(默认 15m);行数/单行长度/总响应均有硬上限,超出会标注省略。排查线上问题建议优先用 diagnose_issue(自动聚合分析),本工具适合按线索精确取证。

Inputs: end, level, limit, range, +9 more.

query_slow_logsA

按耗时阈值抓取慢日志(如执行超过 30s 的慢 SQL)。支持三个维度:sql(每条 SQL 的 queryRows/updateRows Nms)、request(请求级 utime)、connection(连接级 release)。慢 SQL 自动按连接号-序号配对回捞语句原文;命中超 30 条(如循环任务)时自动按操作聚合统计(count/totalMs/maxMs/avgMs),明细仅保留最慢样本。

Inputs: end, kind, level, limit, +10 more.

summarize_errorsA

错误聚合归并:把窗口内错误按模板指纹压缩成少量模式,区分首发错误(可能的原因)与级联噪声(后果),并给出故障类型分类、堆栈业务帧、高频 requestId。比直接翻错误日志高效得多。

Inputs: end, topN, range, start, +4 more.

trace_contextA

按 requestId/traceId 还原单次请求的完整日志链路(时间正序)。定位具体一次失败请求时用它,返回量小且完整。

Inputs: end, range, start, labels, +4 more.

trace_flowA

流程完整性检查("流程走一半没了但不报错"时的首选):取一条链路的日志模板序列,与成功样本序列对比,定位流程在哪一步中断。

Inputs: range, labels, project, traceId, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 15 tools

    Disambiguation4/5

    工具职责整体清晰,但 query_logs 与 trace_context 都涉及查询日志,且 summarize_errors 与 diagnose_issue 有功能重叠;不过描述中给出明确适用场景(如 query_logs 用于按线索取证,trace_context 用于请求链路还原),可有效区分。

    Naming Consistency5/5

    所有工具名均为 snake_case 的动词+名词形式,如 list_datasources、query_slow_logs、diagnose_issue,模式统一,无混合风格,易于预测。

    Tool Count5/5

    15 个工具覆盖日志查询、聚合、诊断、对比、链路追踪等核心场景,每个工具都有明确用途,无明显冗余,规模适中。

    Completeness5/5

    工具集覆盖日志排障的完整生命周期:发现数据源、探索项目与标签、查询原始日志、聚合错误、趋势检测、链路追踪、基线对比、字段检查、流程断点、综合诊断,并生成 Explore 深链,无关键缺口。

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      A read-only MCP server that exposes Quickwit log search and aggregations to LLM clients, enabling natural language log investigation.
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server for querying Sumo Logic logs, enabling AI assistants to search and investigate application logs with opinionated tools and secure credential handling.
      5
      1
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      Read-only MCP server for searching migrated Papertrail logs via SolarWinds Observability API. Provides tools to list environments and perform bearer-authenticated log queries through stdio.
      2
      -