用途
loki-mcp-server 是一个用 Go 编写的 MCP（Model Context Protocol）服务器，目标是让 AI 智能体直接查询 Grafana Loki 日志，而不需要经过 Grafana。它面向 AI 驱动的日志分析场景，使用 LogQL 作为查询语言，可集成到 AI 智能体框架、自动化工具和 DevOps 工作流中。
主要能力
该服务器提供 5 个细粒度工具：
- query_range：执行 LogQL 范围查询，获取某个时间窗口内的日志。
- query：执行 LogQL 即时查询，用于时间点求值。
- labels：列出 Loki 中所有可用的标签名。
- label_values：列出某个特定标签的所有值。
- series：查找匹配选择器的活跃日志流序列。
与官方 grafana/loki-mcp 只暴露单一 loki_query 工具不同，本项目采用“先发现、后查询”的工作流：labels、label_values 和 series 让 LLM 先发现 Loki 中有什么可用，再构造精确的 query_range 或 query 调用，从而获得更准确的日志检索结果并减少无效往返。
此外，服务器实施严格的输入校验，包括 limit 上限、direction 校验、标签名格式检查以及认证方式互斥，以便尽早暴露错误，而不是把错误请求转发给 Loki。
使用方式
服务器完全通过环境变量配置，由 MCP 客户端注入。注意：基本认证（LOKI_USERNAME / LOKI_PASSWORD）与 bearer token（LOKI_BEARER_TOKEN）互斥。
默认情况下，服务器通过 stdio 使用 MCP 协议通信，这是 Claude Code、Claude Desktop 及大多数本地客户端所期望的方式。设置 MCP_HTTP_ADDR 可改为提供 streamable HTTP 传输，用于将服务器作为远程端点运行在代理或网关之后。HTTP 模式是无状态的，因此可以运行在负载均衡器后面并部署多个副本。它自身不携带认证，暴露前应置于 TLS 和认证代理之后；任何能访问该端点的人都可以读取所配置 LOKI_URL 凭据可见的每一行日志。
与 Claude Code 配合使用时，添加到 Claude Code 的 MCP 配置（~/.claude.json）。与 Claude Desktop 配合使用时，添加到 Claude Desktop 配置（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）。
适用场景
- AI 智能体进行日志分析与故障排查。
- 自动化工具和 DevOps 工作流中集成 Loki 日志查询。
- 需要让 LLM 先发现标签和日志流、再构造精确 LogQL 查询的场景。
限制
- HTTP 模式无状态且自身不提供认证，需自行置于 TLS 和认证代理之后。
- 基本认证与 bearer token 互斥，不能同时使用。
- 具体安装命令、构建步骤及配置示例在提供的资料中未完整给出，暂未提供。
本地开发环境
deploy/ 下包含 Docker Compose 配置，可启动完整的 Loki 测试环境：Loki 日志存储位于 http://localhost:3100；Grafana UI 位于 http://localhost:3000（匿名管理员，已预配置 Loki 为数据源）；Promtail 收集容器日志并发送到 Loki；日志生成器发出结构化 JSON 日志，包含随机应用（nginx、api、gateway、auth、payments）、级别和消息。
