Loki MCP Server

Loki MCP Server

一个本地 stdio MCP 服务，可让 Agent 读取 Grafana Loki。它提供五种文本工具，支持 Loki 2.6.1 和 3.x。Loki 本身只读；唯一的写入操作是将 exportLogs 保存到本地文件。

每个数据工具都需要显式指定连接。queryLogs、countLogs 和 exportLogs 需要 LogQL 日志查询，例如 {app="backend"} |= "ERROR"。使用 discoverLogs 查找标签名称、标签值，以及流标签集中的实际组合。服务只会为 countLogs 构建 count_over_time 表达式；它不会推断筛选条件或解释原因。工具响应是易读文本，不包含输出架构。

构建和运行

需要 JDK 21 或更高版本；项目使用 Java 21 工具链和 Gradle 包装器。

.\gradlew.bat bootJar
java -jar build/libs/loki-mcp-server.jar

在 Linux/macOS 上使用 ./gradlew。进程会等待从 stdin 输入 MCP JSON-RPC。stdout 专用于 JSON-RPC；诊断信息会写入 stderr 和 ~/.loki-mcp-server/logs/loki-mcp-server.log。

每个版本都附带预构建的 loki-mcp-server.jar，因此构建并非必需。

对于 Claude Code，注册该 jar 只需一条命令：

claude mcp add --scope user loki -- java -jar /path/to/loki-mcp-server.jar

Docker

每次发布版本时，都会将镜像发布到 GHCR。将存放 connections.json 的目录挂载到 /data；服务也会在此处写入日志和默认导出文件：

docker run -i --rm -v ~/.loki-mcp-server:/data ghcr.io/igorolv/loki-mcp-server:latest

MCP 客户端应启动的也是这条命令；-i 会保持 stdin 打开，以供 stdio 传输使用。connections.json 中的 Loki URL 必须能从容器内部访问：请使用 Loki 主机名而不是 localhost，或者在 Linux 上添加 --network host。位于 /data 之外的 exportLogs 目录是容器内的路径，因此也需要挂载。若要在本地构建镜像：docker build -t loki-mcp-server .

连接

服务会读取 ~/.loki-mcp-server/connections.json，或 LOKI_MCP_CONNECTIONS_FILE 中指定的路径。最精简的文件如下：

{
  "connections": {
    "dev": {
      "description": "Development",
      "hint": "Start with {app=\"backend\"}; inspect app values with discoverLogs.",
      "url": "http://localhost:3100",
      "timezone": "Europe/Moscow",
      "serviceLabels": ["app", "container"]
    }
  }
}

完整示例使用环境变量配置非本地 URL。hint 为模型提供 stand 专用选择器和字段建议。serviceLabels 指定用于在紧凑行中显示服务的标签。可选的 formatFile 用于指定一个包含 JSON 配置文件、纯文本行模式和可选 framePattern 的 JSON 文件；请参阅 log-formats.json。可选的 exportFormat 用于设置 exportLogs 的默认模板，前提是工具调用未提供 format。连接文件可以设置 exportRoots 以限制导出目标位置，并设置每个连接的限制。身份验证和租户标头按连接配置；工具响应或诊断信息中不会出现 URL 和凭据。完整格式请参阅 docs/connections.md。

服务会在启动时严格加载配置，不会探测 Loki。字段未知、键重复、环境变量缺失或格式文件无效，都会导致启动失败并显示安全的配置错误。配置变更需要重启。

使用工具

1. 调用 listConnections，选择一个环境，并根据其显示的时间窗口、queryLogs 行数上限和请求超时来规划调用。
2. 调用 discoverLogs(connection="dev") 获取标签名称，然后调用 discoverLogs(connection="dev", label="app") 获取值。需要查看组合时，使用 discoverLogs(connection="dev", match="{app="backend"}") 获取完整的流标签集合，或添加 label="namespace" 获取这些集合中的命名空间值。保持 match 和时间窗口范围较窄；这些是流标签，而不是日志行数。在日志较少的环境中，可以适当扩大时间窗口。
3. 使用 LogQL 日志查询，通过 countLogs 检查日志量，通过 queryLogs 读取日志行。例如，{app="backend"} |= "ERROR"；groupBy="time", step="1d" 会生成按 UTC 对齐的 24 小时分桶，groupBy="app,time" 会按应用和时间统计数量。命名的 | regexp 捕获可以提供 groupBy 标签。日期标记可区分午夜前后的分桶。
4. 如果页面内容过多，请缩小查询范围。queryLogs 默认显示最新一页；order="oldest" 会从时间窗口的开头开始。页脚会提供更早日志的结束位置或更新日志的起始位置。边界行可能重复；如果同一时间戳包含的日志行数超过一页所需数量，请缩小查询范围。
5. 用户要求生成文件时，调用 exportLogs。将用户指定的目标位置作为 directory 传入，例如 C:\tmp\logs；也可以省略该参数以使用默认导出目录。省略 format 时，会使用连接配置的 exportFormat 模板（如果操作员已设置），否则使用原始格式。format="raw" 会写入 Loki 返回的日志行，包括查询中 | line_format 的转换结果；format="{time} {level} {service} {message}" 会在本地进行格式化。响应会提供路径、数量和实际使用的格式，不包含日志内容。

queryLogs 会按时间顺序打印时间窗口的一端。默认视图会缩短消息和堆栈跟踪，以节省模型令牌。在连接的 formatFile 中，可选的 framePattern 会在紧凑视图中折叠相邻的独立堆栈帧行。raw=true 会显示每一条返回的日志行及其流标签，最多显示 4000 个代码点；这是预览。如需获取完整日志行，请使用 exportLogs。导出会逐页向前读取，且绝不会覆盖已有文件。如果同一纳秒内的日志行数超过 Loki 单页可返回的数量，导出会报告可能有部分日志缺失。

默认时间窗口为 now-1h 到 now。可接受的时间格式包括 now-15m、带偏移量的 RFC3339、连接所在时区的本地时间以及纪元纳秒。queryLogs 和 exportLogs 默认允许一天的时间范围。countLogs 对总数、标签分组或标签与时间组合分组允许一天，对仅按时间分桶允许七天；discoverLogs 不带 match 时允许七天，带 match 时允许一天。Loki 请求的默认超时时间为 30 秒，queryLogs 默认每页最多允许 1000 行。listConnections 会显示每个环境的有效值。默认情况下，导出会在 25 秒后停止；如果已写入日志行，则会报告部分文件及其续传信息。计数超时后，请重试一天的子时间窗口或缩小查询范围。可按连接设置限制；请参阅 docs/queries.md 和 docs/discovery.md。

MCP 客户端配置

Claude Code：

claude mcp add --scope user loki -e LOKI_MCP_CONNECTIONS_FILE=C:/path/connections.json -- java -jar C:/path/loki-mcp-server.jar

Codex (~/.codex/config.toml)：

[mcp_servers.loki]
command = "java"
args = ["-jar", "C:/path/loki-mcp-server.jar"]
env = { LOKI_MCP_CONNECTIONS_FILE = "C:/path/connections.json" }

其他客户端可以通过 stdio 启动 jar。请将 stderr 与 stdout 分开。

错误与诊断

工具失败时会返回文本 Error : ，并设置 isError=true；Spring AI 目前会在第二行重复该文本。缺少参数或参数类型错误时，MCP SDK 会进行输入验证并返回错误。Loki HTTP 400 LogQL 解析错误会被返回，以便模型修正查询。其他上游响应正文、URL、凭据、租户信息和完整日志行不会出现在响应和诊断信息中。404 适用于被调用的端点，而非整个连接。传输详情见 docs/http-client.md。

.\gradlew.bat build
.\gradlew.bat integrationTest --console=plain
python scripts/live_smoke/run_smoke.py --connection dev