mcp-loki

🚀 MCP Loki

MCP Loki 是一个用于查询 Grafana Loki 日志的 MCP 服务器。它借助模型上下文协议，让大语言模型（LLMs）能够搜索和分析日志，极大提升了日志处理和分析的效率。

✨ 主要特性

• LogQL 查询：可执行具有灵活时间范围的范围查询。
• 标签发现：列出标签及其值，方便构建查询。
• 系列探索：查找与标签选择器匹配的日志流。
• 索引统计：获取基数和大小指标。
• 多种认证方式：支持基本认证、Bearer 令牌、多租户（X-Scope-OrgID）。
• 多架构镜像：提供 linux/amd64 和 linux/arm64 架构的镜像。
• 签名镜像：通过 cosign 无密钥签名验证。

🚀 快速开始

容器（Podman/Docker）

将以下内容添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "loki": {
      "command": "podman",
      "args": [
        "run", "--rm", "-i",
        "-e", "LOKI_URL=http://loki:3100",
        "ghcr.io/lexfrei/mcp-loki:latest"
      ]
    }
  }
}

Go 安装

go install github.com/lexfrei/mcp-loki/cmd/mcp-loki@latest

MCP 客户端配置：

{
  "mcpServers": {
    "loki": {
      "command": "mcp-loki",
      "env": {
        "LOKI_URL": "http://loki:3100"
      }
    }
  }
}

📦 安装指南

所有配置均通过环境变量完成： | 变量 | 是否必需 | 默认值 | 描述 | |------|----------|---------|-------------| | LOKI_URL | 否 | http://localhost:3100 | Loki 服务器的 URL | | LOKI_USERNAME | 否 | — | 基本认证的用户名 | | LOKI_PASSWORD | 否 | — | 基本认证的密码 | | LOKI_TOKEN | 否 | — | Bearer 令牌（基本认证的替代方式） | | LOKI_ORG_ID | 否 | — | 多租户 Loki 的 X-Scope-OrgID 头 | | MCP_HTTP_PORT | 否 | — | 在此端口启用 HTTP SSE 传输 |

认证示例

无认证（本地 Loki）：

{
  "command": "podman",
  "args": [
    "run", "--rm", "-i",
    "-e", "LOKI_URL=http://loki:3100",
    "ghcr.io/lexfrei/mcp-loki:latest"
  ]
}

基本认证：

{
  "command": "podman",
  "args": [
    "run", "--rm", "-i",
    "-e", "LOKI_URL=https://loki.example.com",
    "-e", "LOKI_USERNAME=admin",
    "-e", "LOKI_PASSWORD=secret",
    "ghcr.io/lexfrei/mcp-loki:latest"
  ]
}

Bearer 令牌（Grafana Cloud）：

{
  "command": "podman",
  "args": [
    "run", "--rm", "-i",
    "-e", "LOKI_URL=https://logs-prod-us-central1.grafana.net",
    "-e", "LOKI_TOKEN=glc_xxx",
    "-e", "LOKI_ORG_ID=123456",
    "ghcr.io/lexfrei/mcp-loki:latest"
  ]
}

💻 使用示例

可用工具

loki_query

对 Loki 执行 LogQL 查询。 | 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | query | 字符串 | 是 | LogQL 查询字符串 | | start | 字符串 | 否 | 开始时间（RFC3339 格式、相对时间如 1h 或 now） | | end | 字符串 | 否 | 结束时间（RFC3339 格式、相对时间或 now） | | limit | 整数 | 否 | 要返回的最大条目数（默认：100） | | direction | 字符串 | 否 | forward 或 backward（默认：backward） |

示例：

查询最近一小时的 nginx 错误日志：
- query: {app="nginx"} |= "error"
- start: 1h
- limit: 50

loki_labels

获取特定标签的名称或值。 | 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | name | 字符串 | 否 | 要获取值的标签名称（省略则获取所有标签） | | start | 字符串 | 否 | 开始时间 | | end | 字符串 | 否 | 结束时间 |

示例：

获取所有标签名称：（无参数）
获取 "app" 标签的值：name=app

loki_series

查找与标签选择器匹配的日志流。 | 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | match | 字符串数组 | 是 | 标签选择器，例如 {app="nginx"} | | start | 字符串 | 否 | 开始时间 | | end | 字符串 | 否 | 结束时间 |

示例：

查找所有 nginx 日志流：match=["{app=\"nginx\"}"]

loki_stats

获取查询的索引统计信息。 | 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | query | 字符串 | 是 | LogQL 选择器 | | start | 字符串 | 否 | 开始时间 | | end | 字符串 | 否 | 结束时间 |

示例：

获取 nginx 日志的统计信息：query={app="nginx"}

时间格式

所有时间参数支持以下格式：

• RFC3339：2024-01-15T10:30:00Z
• 相对时间：30s、5m、1h、7d（分别表示秒、分钟、小时、天前）
• 关键字：now

🔧 技术细节

容器镜像通过 cosign 无密钥签名进行验证：

cosign verify ghcr.io/lexfrei/mcp-loki:latest \
  --certificate-identity-regexp=https://github.com/lexfrei/mcp-loki \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com

📄 许可证

本项目采用 BSD-3-Clause 许可证。