grafana-log-mcp
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-mcpTras 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-mcpDesarrollo 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.jsIntegració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 |
| Enumeración de múltiples fuentes de datos, descubrimiento de proyectos (incluidas apps/grupos no registrados) |
Metadatos |
| Etiquetas y sus valores |
Consulta |
| Logs sin procesar (prioriza requestId + ventana de tiempo estrecha para controlar el volumen de datos) |
Consulta |
| 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 |
| 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 |
| Clasificación y jerarquización de errores, picos de volumen, trazado de una sola solicitud |
Sin errores |
| Plantillas de logs desaparecidas, campos con valores nulos, puntos de interrupción del flujo |
Orquestación |
| Primera opción para solucionar problemas: un solo informe de diagnóstico + codeHints |
Utilidades |
| 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):
El archivo especificado por la variable de entorno
GRAFANA_CONFIG_PATHconfig/projects.jsondentro del paquete (en el repositorio de código fuente)~/.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 toolsbuild_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
Scored across 15 tools
工具职责整体清晰,但 query_logs 与 trace_context 都涉及查询日志,且 summarize_errors 与 diagnose_issue 有功能重叠;不过描述中给出明确适用场景(如 query_logs 用于按线索取证,trace_context 用于请求链路还原),可有效区分。
所有工具名均为 snake_case 的动词+名词形式,如 list_datasources、query_slow_logs、diagnose_issue,模式统一,无混合风格,易于预测。
15 个工具覆盖日志查询、聚合、诊断、对比、链路追踪等核心场景,每个工具都有明确用途,无明显冗余,规模适中。
工具集覆盖日志排障的完整生命周期:发现数据源、探索项目与标签、查询原始日志、聚合错误、趋势检测、链路追踪、基线对比、字段检查、流程断点、综合诊断,并生成 Explore 深链,无关键缺口。
Maintenance
Related MCP Connectors
A paid remote MCP for AI SDK data query MCP, built to return verdicts, receipts, usage logs, and aud
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server for querying Grafana Loki directly with a discovery-first workflow — labels, values, series, and LogQL queries without requiring Grafana.58MIT
- AlicenseNot gradedqualityFmaintenanceA read-only MCP server that exposes Quickwit log search and aggregations to LLM clients, enabling natural language log investigation.Apache 2.0
- AlicenseAqualityDmaintenanceA 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.51MIT
- FlicenseAqualityCmaintenanceRead-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-