AI导哈

Loki日志查询服务器

一个为Grafana Loki设计的AI友好型MCP服务器，提供42种工具覆盖Loki的HTTP API，并支持高级工具让LLM无需了解LogQL即可搜索日志。

  • by abl030
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 abl030/loki-mcp

使用说明

洛基·麦克普

AI友好的MCP服务器 格拉法娜·洛基提供了42个工具，涵盖了Loki的HTTP API的100%，以及让LLM在不知道LogQL的情况下搜索日志的高级工具。

为什么？

现有 mcp-loki 给你3个原始工具(loki_query, loki_label_names, loki_label_values)并期望LLM编写LogQL。本项目：

  • 42工具 -每个API操作一个，带有类型化参数和丰富的文档字符串
  • 不需要LogQL --高级工具，如 loki_search_logs 从结构化参数构建查询
  • 确认闸门 --突变（推送、删除、刷新、关闭）需要 confirm=True
  • 模块过滤 --仅启用所需的模块
  • 只读模式 --剥离所有写入操作
  • 100%测试 --20个单元测试+36个针对Loki实例的集成测试

快速开始

Nix（推荐）

nix run github:abl030/loki-mcp

MCP客户端配置

添加到MCP客户端配置中（例如。 .mcp.json):

{
  "mcpServers": {
    "loki": {
      "command": "nix",
      "args": ["run", "github:abl030/loki-mcp"],
      "env": {
        "LOKI_URL": "https://loki.example.com:3100"
      }
    }
  }
}

紫外线（无镍）

git clone https://github.com/abl030/loki-mcp.git
cd loki-mcp
uv run fastmcp run generated/server.py

配置

所有配置都是通过环境变量进行的：

变量 默认值 描述
LOKI_URL http://localhost:3100 洛基基本URL
LOKI_USERNAME （无） 基本身份验证用户名
LOKI_PASSWORD （无） 基本身份验证密码
LOKI_TOKEN （无） 承载令牌（基本身份验证的替代方案）
LOKI_ORG_ID （无） 多租户组织ID(X-Scope-OrgID 头球
LOKI_VERIFY_SSL false 验证SSL证书
LOKI_MODULES （全部） 启用逗号分隔的模块
LOKI_READ_ONLY false 删除所有突变工具
LOKI_TIMEOUT 30 HTTP请求超时（秒）

模块过滤

通过设置限制可用的工具组 LOKI_MODULES:

# Only expose query and status tools
LOKI_MODULES=query,status

只读模式

剥离所有写入操作（推送、删除、规则CRUD、管理员突变）：

LOKI_READ_ONLY=true

工具清单

高级工具（不需要LogQL）

这些是大多数LLM应该使用的工具——它们在内部构建LogQL：

工具 说明
loki_search_logs 按主机、容器、单元、模式、严重性搜索
loki_error_summary 主机容器间的聚合错误
loki_volume_by_label 按日志卷查找最嘈杂的主机/容器
loki_compare_hosts 主机间并行日志比较
loki_get_overview 系统摘要（运行状况、版本、标签、主机）
loki_validate_query 检查LogQL查询是否有效
loki_search_tools 在所有工具名称/描述中进行关键字搜索
loki_report_issue 生成结构化错误报告

查询模块（6个工具）

工具 方法 端点
loki_query_instant 得到 /loki/api/v1/query
loki_query_range 得到 /loki/api/v1/query_range
loki_list_labels 得到 /loki/api/v1/labels
loki_list_label_values 得到 /loki/api/v1/label/{name}/values
loki_list_series 得到 /loki/api/v1/series
loki_format_query 得到 /loki/api/v1/format_query

索引模块（3个工具）

工具 方法 端点
loki_index_stats 得到 /loki/api/v1/index/stats
loki_index_volume 得到 /loki/api/v1/index/volume
loki_index_volume_range 得到 /loki/api/v1/index/volume_range

模式模块（1个工具）

工具 方法 端点
loki_detect_patterns 得到 /loki/api/v1/patterns

摄入模块（1个工具）

工具 方法 端点
loki_push 职位 /loki/api/v1/push

规则模块（7个工具）

工具 方法 端点
loki_list_rules 得到 /loki/api/v1/rules
loki_get_rules_namespace 得到 /loki/api/v1/rules/{namespace}
loki_get_rule_group 得到 /loki/api/v1/rules/{namespace}/{group}
loki_create_rule_group 职位 /loki/api/v1/rules/{namespace}
loki_delete_rule_group 删除 /loki/api/v1/rules/{namespace}/{group}
loki_delete_rules_namespace 删除 /loki/api/v1/rules/{namespace}
loki_list_prometheus_rules 得到 /prometheus/api/v1/rules

删除模块（3个工具）

工具 方法 端点
loki_create_delete_request 职位 /loki/api/v1/delete
loki_list_delete_requests 得到 /loki/api/v1/delete
loki_cancel_delete_request 删除 /loki/api/v1/delete

状态模块（7个工具）

工具 方法 端点
loki_ready 得到 /ready
loki_metrics 得到 /metrics
loki_config 得到 /config
loki_services 得到 /services
loki_buildinfo 得到 /loki/api/v1/status/buildinfo
loki_get_log_level 得到 /log_level
loki_set_log_level 职位 /log_level

管理模块（6个工具）

工具 方法 端点
loki_flush 职位 /flush
loki_prepare_shutdown_status 得到 /ingester/prepare_shutdown
loki_prepare_shutdown 职位 /ingester/prepare_shutdown
loki_cancel_prepare_shutdown 删除 /ingester/prepare_shutdown
loki_shutdown_status 得到 /ingester/shutdown
loki_shutdown 职位 /ingester/shutdown

建筑

spec/endpoint-inventory.json  -->  generator/  -->  templates/server.py.j2  -->  generated/server.py

服务器是 代码生成 来自手工制作的端点规范（Loki没有OpenAPI）。要更新，请执行以下操作：

# Edit spec/endpoint-inventory.json
# Then regenerate:
nix develop -c python -m generator

测试

单元测试（无需基础设施）

nix develop -c python -m pytest tests/test_naming.py tests/test_modules.py tests/test_list_tools.py -v

集成测试（需要Docker）

# Start Loki test stack
docker compose -f docker/docker-compose.yml up -d

# Wait for ready + seed test data
bash docker/wait-for-ready.sh

# Run 36 integration tests
nix develop -c python -m pytest tests/test_integration.py -v --integration

# Tear down
docker compose -f docker/docker-compose.yml down

Docker堆栈包括：

  • 洛基3.4.2 （单个二进制，启用所有功能）
  • 合金 （原木收集者刮擦垃圾箱）
  • 鞭打 （4个容器在2个模拟主机上生成真实的日志）
  • 格拉法纳 （可选， --profile debug)

已知限制

  • WebSocket尾部 (/loki/api/v1/tail)--FastMCP的传输不支持
  • OTLP摄入 (/otlp/v1/logs)--收集器协议，对AI代理无效
  • CRUD规则 -需要带远程存储的Loki标尺（本地存储对于API写入是只读的）
  • 获取 /ingester/shutdown --可能会触发Loki 3.4.x中的实际关机（谨慎使用）

许可证

麻省理工学院

相关 MCP