AI导哈

Loki查询服务

一个为AI代理和自动化设计的Grafana Loki查询服务，提供16种只读MCP工具，支持发现、查询、分析和健康检查。

  • by jpetrucciani
  • Rust
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 jpetrucciani/loki-mcp

使用说明

洛基·麦克普

loki-mcp 是一个用于查询Grafana Loki的模型上下文协议（MCP）服务器，专为AI代理和自动化而构建。

特性

  • 16个只读MCP工具，用于发现、查询、分析和健康检查
  • 配置分层和验证： TOML -> env -> CLI
  • Loki身份验证模式： none, basic, bearer
  • MCP和调试端点的可选静态标头身份验证
  • 基于浏览器的MCP客户端的可选CORS分配列表
  • 具有故障关闭行为的字节/流限制护栏
  • 每个工具和每个身份的速率限制
  • 大型结果集的响应模式： raw, truncated, summary, smart
  • 内置可观察性： /healthz, /readyz, /metrics、请求ID、最近的操作跟踪
  • 测试/构建/格式化/clippy的CI覆盖率，以及标记的发布自动化

MCP工具表面

发现：

  • loki_describe_schema
  • loki_list_labels
  • loki_label_values
  • loki_search_label_values
  • loki_series

查询与执行：

  • loki_query_logs
  • loki_query_metrics
  • loki_build_query
  • loki_tail
  • loki_run_saved_query
  • loki_query_stats

分析和创作：

  • loki_detect_patterns
  • loki_compare_ranges
  • loki_explain_query
  • loki_suggest_metric_rule

公用设施：

  • loki_check_health

安装

选项1：发布二进制文件

从以下网址下载适用于您平台的存档 GitHub 发布，提取并放置 loki-mcp 在你的 PATH.

选项2：从源代码构建

cargo build --release
./target/release/loki-mcp --help

选项3：容器图像

标签发布将多拱形图像发布到GHCR：

docker run --rm -p 8080:8080 \
  -v "$PWD/config.toml:/config.toml:ro" \
  ghcr.io/jpetrucciani/loki-mcp:vX.Y.Z \
  --config /config.toml

快速入门

本节假设 loki-mcp 在你的 PATH如果没有，请使用 ./target/release/loki-mcp.

  1. 复制示例配置：
cp config.example.toml config.toml
  1. 编辑 config.toml 并设置 loki.url 以及您环境的身份验证字段。
  2. 启动服务器：
loki-mcp --config config.toml
  1. 验证本地端点：
curl -fsS http://127.0.0.1:8080/healthz
curl -fsS http://127.0.0.1:8080/readyz
curl -fsS http://127.0.0.1:8080/metrics | head

MCP传输端点： http://127.0.0.1:8080/mcp

配置

config.example.toml 是参考模板。

优先级（从低到高）：

  1. TOML文件
  2. 环境变量
  3. CLI标志

示例：

# explicit config path
loki-mcp --config /etc/loki-mcp/config.toml

# config path via env
LOKI_MCP_CONFIG=/etc/loki-mcp/config.toml loki-mcp

# CLI override
loki-mcp --config config.toml --listen 0.0.0.0:8080 --loki-url https://loki:3100

# enable static-header auth for /mcp and /debug/*
loki-mcp --config config.toml --auth-token "$LOKI_MCP_TOKEN"

# allow a browser-based MCP client origin
loki-mcp --config config.toml --cors-allowed-origin http://localhost:6274

# flattened env aliases
LOKI_MCP_LOKI_URL=https://loki:3100 LOKI_MCP_LISTEN=0.0.0.0:8080 loki-mcp

LOKI_MCP_AUTH_TOKEN="$LOKI_MCP_TOKEN" loki-mcp

LOKI_MCP_CORS_ALLOWED_ORIGINS=http://localhost:6274,https://app.example.com loki-mcp

# nested env form (double underscore)
LOKI_MCP_LOKI__URL=https://loki:3100 LOKI_MCP_SERVER__LISTEN=0.0.0.0:8080 loki-mcp

常见环境密钥：

  • LOKI_MCP_LISTEN
  • LOKI_MCP_TIMEZONE
  • LOKI_MCP_LOG_LEVEL
  • LOKI_MCP_IDENTITY_HEADER
  • LOKI_MCP_AUTH_HEADER
  • LOKI_MCP_AUTH_TOKEN
  • LOKI_MCP_CORS_ALLOWED_ORIGINS
  • LOKI_MCP_LOKI_URL
  • LOKI_MCP_LOKI_TENANT_ID
  • LOKI_MCP_LOKI_AUTH_TYPE
  • LOKI_MCP_LOKI_USERNAME
  • LOKI_MCP_LOKI_PASSWORD
  • LOKI_MCP_LOKI_TOKEN
  • LOKI_MCP_LOKI_CA_CERT
  • LOKI_MCP_RATE_LIMIT_RPS
  • LOKI_MCP_GUARDRAILS_MAX_BYTES_SCANNED
  • LOKI_MCP_RECENT_ACTIONS_ENABLED

安全和信任模型

洛基认证：

  • loki.auth_type=none
  • loki.auth_type=basic 需要 username 和 password
  • loki.auth_type=bearer 需要 token

使用环境变量作为机密，而不是将凭据提交给TOML。

MCP认证：

  • 除非满足以下条件，否则禁用静态标头身份验证 server.auth_token 已设置。
  • 当启用时， GET 和 POST /mcp 和 /debug/* 请求必须包含具有确切令牌值的配置标头。
  • 默认标题为 x-loki-mcp-token；用以下命令覆盖它 server.auth_header, --auth-header，或 LOKI_MCP_AUTH_HEADER.
  • GET /healthz, GET /readyz，以及 GET /metrics 对于探测和刮擦，保持未经身份验证。
  • 对于OIDC/JWT/mTLS或按用户授权，部署 loki-mcp 在可信的反向代理/入口后面。
  • 使用代理时，剥离可伪造的入站身份标头，转发受信任的身份标头，并设置 server.identity_header 为了匹配。

例子：

LOKI_MCP_AUTH_TOKEN="$LOKI_MCP_TOKEN" loki-mcp
curl -H "x-loki-mcp-token: $LOKI_MCP_TOKEN" http://127.0.0.1:8080/mcp

CORS：

  • CORS被禁用，除非 server.cors_allowed_origins 不是空的。
  • 例如，允许的来源必须是唯一的来源 http://localhost:6274，而不是像这样的路径 http://localhost:6274/mcp.
  • 使用 server.cors_allowed_origins = ["*"], --cors-allowed-origin '*'，或 LOKI_MCP_CORS_ALLOWED_ORIGINS='*' 允许任何浏览器来源。
  • 通配符CORS对于本地检查很有用，但对于共享部署来说，确切的来源更好。
  • CORS预检请求在静态头认证之前处理，因为浏览器不会在预检时发送自定义认证头。

MCP Inspector经常从与以下不同的本地主机运行浏览器UI loki-mcp。如果检查器报告CORS失败，请启动 loki-mcp 使用检查器源，或使用通配符CORS进行本地调试：

LOKI_MCP_CORS_ALLOWED_ORIGINS='*' loki-mcp

速率限制标识密钥按以下顺序解析：

  1. 配置 identity_header
  2. 第一跳 x-forwarded-for
  3. 远程IP

运行时行为

时间处理：

  • 如果 start 和 end 在查询工具上省略，默认范围为最后一个 30m 结束于 now
  • start 和 end 接受RFC3339，现代Unix纪元秒，持续时间如下 15m, now, today, yesterday，以及 since 2pm
  • 工具与 start/end 也接受 range例如 {"range": "10m"} 在最后10分钟。 range 可以与 end，但不是与 start

标签发现：

  • loki_label_values 支持 prefix 和 pattern 除了Loki的子字符串过滤器 query 选择器范围
  • loki_search_label_values 搜索所有标签，或提供 labels list，并且只返回匹配的值 prefix 或 pattern
  • loki_tail 接受其中之一 labels 或LogQL query例如 {cluster="cy1-service-01",service_name=~"bot.*"}

响应模式(loki_query_logs, loki_build_query, loki_tail, loki_run_saved_query):

  • raw, truncated, summary, smart （默认）
  • smart 阈值是 <= 50 线条=> raw, 51-500 => truncated, > 500 => summary

护栏：

  • 通过预检查查询成本 /loki/api/v1/index/stats
  • 如果需要，返回运行时统计数据
  • 当估计值不可用时，失败关闭
  • 通过调谐 [guardrails] (max_bytes_scanned, max_streams，以及相关跳过）

缓存和最近的操作：

  • 由控制的内存缓存 [cache]
  • /readyz 结果被短暂缓存以减少探测负载
  • 通过以下方式选择有界的最近行动历史 [recent_actions] (/debug/recent-actions)

HTTP端点

  • GET /healthz，活力
  • GET /readyz，准备就绪(200 健康， 503 不健康）
  • GET /metrics普罗米修斯指标
  • GET 和 POST /mcp，MCP流式HTTP，静态标头在以下情况下受到保护 server.auth_token 已设置
  • GET /debug/recent-actions?limit=100，最近的工具活动(404 禁用时），静态标头受保护时 server.auth_token 已设置

每个HTTP响应都包括 x-request-id.

指标使用 [metrics].prefix （默认值： loki_mcp):

  • <prefix>_http_requests_total
  • <prefix>_tool_calls_total{tool,outcome}
  • <prefix>_tool_cache_total{tool,result}
  • <prefix>_tool_guardrail_rejections_total{tool}
  • <prefix>_tool_rate_limited_total{tool}
  • <prefix>_readiness_cache_total{result}

CLI测试

CLI工具不受浏览器CORS检查的约束。使用 curl 将MCP/auth故障与浏览器源故障分开。

检查CORS飞行前行为：

curl -i -X OPTIONS http://127.0.0.1:8080/mcp \
  -H 'Origin: http://localhost:6274' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type,x-loki-mcp-token,mcp-session-id'

预期有匹配的CORS分配列表： 204 No Content 和一个 access-control-allow-origin 头球

发送MCP初始化请求：

curl -i http://127.0.0.1:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "x-loki-mcp-token: $LOKI_MCP_TOKEN" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "curl", "version": "0.0.0"}
    }
  }'

如果禁用静态标头身份验证，则省略 x-loki-mcp-token 头球

发展

Nix第一个局部外壳：

nix-shell

CI奇偶校验：

cargo fmt -- --check
cargo clippy --all --benches --tests --examples --all-features -- -D warnings -W clippy::collapsible_else_if
cargo test --verbose

集成测试需要本地 loki 二进制开启 PATH.

真正的Loki集成测试是可选的：

LOKI_MCP_RUN_REAL_LOKI_TESTS=1 cargo test --test loki_client_it --test tool_router_it --verbose

故障排除

  • guardrail pre-check failed ...，洛基无法提供成本估算、缩小选择器/范围或调整护栏
  • query rejected by guardrail ...，查询超出了配置的字节/流限制
  • rate limit exceeded ...，增加 [rate_limit] 限制或配置更强 identity_header
  • loki process did not become ready 在测试中，验证 loki --version 以及环回端口可用性
  • loki_check_health 报告 /ready 404，当其他Loki API可访问时，通常在网关/代理后面预期
  • 针对Loki的TLS故障，已设置 loki.ca_cert 对于私人CA
  • /debug/recent-actions 返回404，set [recent_actions].enabled=true
  • /mcp 或 /debug/* 返回401，发送配置的auth头或取消设置 server.auth_token
  • MCP检查器报告CORS错误，将其浏览器源添加到 server.cors_allowed_origins 或使用 ["*"] 用于本地调试

相关 MCP