grafana-log-mcp

grafana-log-mcp is a generic, reusable log-querying layer for Grafana/Loki, exposed as a read-only stdio MCP server. It talks to Grafana's API and returns raw logs plus aggregated views — slow queries, error fingerprints, and volume trends — filtered by time window, project, keyword, or duration threshold.

It deliberately ships no business-specific logic or heuristics. Once the logs are in hand, correlating them with source code and explaining why something happened is left to your AI IDE and the skills/rules of the business project being debugged — the server just makes the data available.

中文定位：这是一个通用的日志查询层（仅做取数、聚合、返回日志，跨业务复用），不内置任何业务分析与根因归因；具体原因分析由调用方的 AI 结合业务项目源码及项目自身的 skill/经验完成。

安装

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

全局安装后提供两个命令：grafana-log-mcp（启动 MCP Server）、grafana-log-mcp-login（交互登录）。

也可不安装、用 npx 一次性运行：npx -y grafana-log-mcp / npx -y grafana-log-mcp-login。

快速开始

npm 已安装（消费方）

# 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

源码开发（clone 仓库后）

# 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

接入 AI IDE（Trae/Claude 等）

在 MCP 配置中添加（按各 IDE 的配置格式）：

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

推荐全局启用：排障时打开的是业务项目源码仓库，把 MCP 配置加为全局，即可在任意仓库直接"提问 → 查日志 → 读代码 → 给原因"。

工具（15 个）

层	工具	用途
发现	list_datasources / list_projects	多数据源枚举、项目发现（含未登记的 app/group）
元数据	list_labels / list_label_values	标签与取值
查询	query_logs	原始日志（优先 requestId + 窄时间窗控制数据量）
查询	get_full_line	取回单条日志完整原文（单行 500 截断时，按该行 time 作 timestamp 查询）
查询	query_slow_logs	按耗时阈值抓慢日志（如 >30s 的慢 SQL），自动配对回捞 SQL 语句原文；命中超 30 条（循环任务）时自动按操作聚合
有报错	summarize_errors / logs_volume / trace_context	错误归并分级、量级突增、单请求链路
无报错	compare_baseline / inspect_fields / trace_flow	消失的日志模板、空值字段、流程断点
编排	diagnose_issue	排障首选：一次调用出诊断报告 + codeHints
辅助	build_explore_url	生成 Grafana Explore 深链供人工核对

数据量三道硬上限：limit ≤ 1000、单行 500 字符、响应 25k 字符（超出保头尾省中段并标注）。单行被截断时可用 get_full_line 按该行 time 取回完整内容。

项目登记（projects.json）

登记文件按以下优先级定位（list_projects 返回的 summary.configFile 会显示当前实际生效位置）：

1. GRAFANA_CONFIG_PATH 环境变量指定的文件
2. 包内 config/projects.json（源码仓库内）
3. ~/.grafana-log-mcp/projects.json（与凭证同目录，npm 安装后的默认位置）

参考格式见 config/projects.example.json，每项含 key / datasourceUid / labels{app,group} / aliases(中文别名) / repoPath。repoPath 仅供 AI IDE 定位代码用，MCP 自身不读源码。故障知识库在 config/failure-patterns.json，遇到新故障类型追加条目即可。

环境变量（可选）

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 条合成日志，验证翻页/截断/慢日志）

说明：MCP 不内置任何 Grafana 默认地址与项目配置（通用化），地址来自登录时输入（凭证文件）或 GRAFANA_URL 环境变量；实例相关配置（项目登记、数据源 uid）在 projects.json 维护（见上节定位规则）。

测试

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