grafana-mcp

将部分 Grafana API 作为 MCP（模型上下文协议）服务器公开，专注于自然语言日志查询。主要目标：说“显示过去 30 分钟内 api 服务的错误日志”，即可获取实际的日志行 —— 无需手动处理 LogQL、标签或数据源 UID。

日志数据源、Loki 标签以及从服务名称到其托管数据源/标签的映射都会缓存在磁盘上，因此重复调用可以跳过冗余的标签扫描。

한국어 문서 / Korean README

安装与设置

npx（无需安装）

将以下内容添加到 ~/.mcp.json。

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@seungje.jun/grafana-mcp"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

从源码构建

git clone https://github.com/ninanung/grafana-mcp.git
cd grafana-mcp
npm install
npm run build

{
  "mcpServers": {
    "grafana": {
      "command": "node",
      "args": ["/path/to/grafana-mcp/dist/cli.js"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

重启 Claude Code 以激活 MCP 工具。

身份验证

需要以下其中一项。它们按以下顺序检查 —— 找到的第一个有效。

所有 Bearer 类型的令牌均作为 Authorization: Bearer <token> 发送。服务器不关心令牌的类型 —— 它只选择已设置的那一个。

环境变量

Related MCP server: Log Analyzer MCP Server

工具

使用示例

由 MCP 客户端编排的典型自然语言流程：

1. 用户：“显示过去 30 分钟内 api 服务的错误日志。”

2. 使用 service: "api"、level: "error"、time_from: "now-30m" 调用 query_logs → 服务器自动检测哪个 Loki 数据源拥有 service="api" 标签并运行 LogQL。

3. (首次调用) 服务 → 数据源/标签映射被保存到缓存中；后续调用跳过检测步骤。

4. 用户：“按模式总结这些错误。” → 使用 output: "summarize" 进行相同的调用，返回按模式分组的计数。

5. 用户：“我们还有哪些其他服务？” → list_services 返回完整的服务列表。

如果服务名称有拼写错误，query_logs 会显示相近的匹配项（例如 Did you mean: checkout, checkout-api?）。

自动检测的工作原理

query_logs 自行选择目标数据源和标签：

1. 将所有数据源过滤为日志类型（Loki/ES/CloudWatch/OpenSearch/Splunk）。

2. 对于每个 Loki 数据源，获取 /loki/api/v1/labels 并首先遍历常见的服务标签候选者（service、service_name、app、app_name、application、container、job），然后遍历任何剩余的标签。

3. 对于每个候选标签，获取其值并检查请求的 service 名称是否在该列表中。

4. 如果恰好有一个 (datasource, label) 对匹配，则使用它。如果多个匹配，则需要 datasource_uid 来消除歧义。如果没有匹配项，则返回名称相近的建议。

5. 解析后的 (service → ds_uid, label) 会被缓存；refresh: true 或 refresh_log_cache 会强制重新检测。

自动检测目前仅支持 Loki。对于 Elasticsearch / CloudWatch / Splunk 数据源，请显式传递 datasource_uid 和 service_label（并且不要指望 LogQL 特定的过滤器适用）。

输出模式

query_logs 接受 output 参数：

• raw (默认): <ISO timestamp> <log line> — 适合在终端中直接阅读。

• summarize: 按标准化模式（数字 → N，UUID → UUID）对行进行分组，并显示每个模式的计数和样本。当日志行嘈杂或过多时使用。

• json: 结构化对象 { ts, line, labels } — 用于下游工具。

缓存

• 日志缓存: 持久化到 ~/.grafana-mcp/log-cache.json。按 Grafana 基础 URL 键控，因此多个实例不会冲突。

• 每个类别都有自己的 TTL（数据源 / 标签 / 标签值 / 服务解析） — 请参阅上面的环境变量表。

• 稍后失败的缓存服务解析（例如标签被重命名）会自动失效，以便下一次调用重新检测。

• 使用 get_log_cache 进行检查，使用 refresh_log_cache 进行清除，使用 export_log_cache / import_log_cache 与团队成员共享。

缓存位置与重置

缓存文件是一个纯 JSON 文档 — 可以安全地手动检查、编辑或备份。

安全与约束

• 只读: 服务器不公开任何改变 Grafana 状态的端点。没有仪表板/数据源的 CRUD，也没有警报更改。

• Stdio 日志: 所有日志都发送到 stderr，保持 MCP stdio 通道干净。

• TLS 跳过: GRAFANA_TLS_SKIP_VERIFY=true 会在进程范围内设置 NODE_TLS_REJECT_UNAUTHORIZED=0。仅在受信任网络中的自签名 Grafana 上使用。

• 无秘密日志记录: 身份验证令牌永远不会写入审计日志。

许可证

MIT