Loki MCP 服务器

一个基于 Go 的服务器实现，用于模型上下文协议 (MCP)，并集成了 Grafana Loki。

入门

前提条件

• Go 1.16 或更高版本

构建和运行

构建并运行服务器：

# 构建服务器
go build -o loki-mcp-server ./cmd/server

# 运行服务器
./loki-mcp-server

或者直接使用 Go 运行：

go run ./cmd/server

服务器使用 stdin/stdout 进行通信，遵循模型上下文协议 (MCP)。 这使其适合与 Claude Desktop 和其他 MCP 兼容的客户端一起使用。 它不作为 HTTP 服务器在端口上运行。

项目结构

.
├── cmd/
│   ├── server/       # MCP 服务器实现
│   └── client/       # 用于测试 MCP 服务器的客户端
├── internal/
│   ├── handlers/     # 工具处理程序
│   └── models/       # 数据模型
├── pkg/
│   └── utils/        # 实用函数和共享代码
└── go.mod            # Go 模块定义

MCP 服务器

Loki MCP 服务器实现了模型上下文协议 (MCP)，并提供以下工具：

Loki 查询工具

loki_query 工具允许您查询 Grafana Loki 日志数据：

• 必需参数：

  • query: LogQL 查询字符串

• 可选参数：

  • url: Loki 服务器 URL（默认：来自 LOKI_URL 环境变量或 http://localhost:3100）
  • start: 查询的开始时间（默认：1 小时前）
  • end: 查询的结束时间（默认：现在）
  • limit: 要返回的最大条目数（默认：100）

环境变量

Loki 查询工具支持以下环境变量：

• LOKI_URL: 如果请求中未指定，则使用的默认 Loki 服务器 URL

测试 MCP 服务器

您可以使用提供的客户端测试 MCP 服务器：

# 构建客户端
go build -o loki-mcp-client ./cmd/client

# Loki 查询示例：
./loki-mcp-client loki_query "{job=\"varlogs\"}"
./loki-mcp-client loki_query "http://localhost:3100" "{job=\"varlogs\"}"
./loki-mcp-client loki_query "{job=\"varlogs\"}" "-1h" "now" 100

# 使用环境变量：
export LOKI_URL="http://localhost:3100"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

Docker 支持

您可以使用 Docker 构建和运行 MCP 服务器：

# 构建 Docker 镜像
docker build -t loki-mcp-server .

# 运行服务器
docker run --rm -i loki-mcp-server

或者，您可以使用 Docker Compose：

# 使用 Docker Compose 构建和运行
docker-compose up --build

使用 Loki 进行本地测试

该项目包含一个完整的 Docker Compose 设置，用于在本地测试 Loki 查询：

1. 启动 Docker Compose 环境：

   docker-compose up -d
   

   这将启动：

   • 端口 3100 上的 Loki 服务器
   • 端口 3000 上的 Grafana 实例（预配置了 Loki 作为数据源）
   • 一个日志生成器容器，它将示例日志发送到 Loki
   • Loki MCP 服务器

2. 使用提供的测试脚本查询日志：

   # 使其可执行
   chmod +x test-loki-query.sh
   
   # 使用默认参数运行（查询最近 15 分钟的日志）
   ./test-loki-query.sh
   
   # 查询错误日志
   ./test-loki-query.sh '{job="varlogs"} |= "ERROR"'
   
   # 指定自定义时间范围和限制
   ./test-loki-query.sh '{job="varlogs"}' '-1h' 'now' 50
   

3. 插入用于测试的虚拟日志：

   # 使其可执行
   chmod +x insert-loki-logs.sh
   
   # 插入 10 个具有默认设置的虚拟日志
   ./insert-loki-logs.sh
   
   # 插入 20 个具有自定义作业和应用程序名称的日志
   ./insert-loki-logs.sh --num 20 --job "custom-job" --app "my-app"
   
   # 插入具有自定义环境和间隔的日志
   ./insert-loki-logs.sh --env "production" --interval 0.5
   
   # 显示帮助消息
   ./insert-loki-logs.sh --help
   

4. 访问 http://localhost:3000 上的 Grafana UI 以可视化地浏览日志。

架构

Loki MCP 服务器使用模块化架构：

• 服务器: cmd/server/main.go 中的主要 MCP 服务器实现
• 客户端: cmd/client/main.go 中用于与 MCP 服务器交互的测试客户端
• 处理程序: internal/handlers/ 中的各个工具处理程序
  • loki.go: Grafana Loki 查询功能

与 Claude Desktop 一起使用

您可以将此 MCP 服务器与 Claude Desktop 一起使用，以添加 Loki 查询工具。 请按照以下步骤操作：

选项 1：使用编译后的二进制文件

1. 构建服务器：

go build -o loki-mcp-server ./cmd/server

2. 使用 claude_desktop_config_binary.json 将配置添加到您的 Claude Desktop 配置文件。

选项 2：使用 Go Run 和 Shell 脚本

1. 使脚本可执行：

chmod +x run-mcp-server.sh

2. 使用 claude_desktop_config_script.json 将配置添加到您的 Claude Desktop 配置文件。

选项 3：使用 Docker（推荐）

1. 构建 Docker 镜像：

docker build -t loki-mcp-server .

2. 使用 claude_desktop_config_docker.json 将配置添加到您的 Claude Desktop 配置文件。

配置详情

Claude Desktop 配置文件位于：

• 在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json
• 在 Windows 上：%APPDATA%\Claude\claude_desktop_config.json
• 在 Linux 上：~/.config/Claude/claude_desktop_config.json

您可以使用此存储库中提供的示例配置之一：

• claude_desktop_config.json: 通用模板
• claude_desktop_config_example.json: 使用 go run 和当前路径的示例
• claude_desktop_config_binary.json: 使用编译后的二进制文件的示例
• claude_desktop_config_script.json: 使用 shell 脚本的示例（推荐用于 go run）
• claude_desktop_config_docker.json: 使用 Docker 的示例（最可靠）

注意:

• 当将 go run 与 Claude Desktop 一起使用时，您可能需要在脚本和配置文件中设置多个环境变量：

  • HOME: 用户的 home 目录
  • GOPATH: Go 工作区目录
  • GOMODCACHE: Go 模块缓存目录
  • GOCACHE: Go 构建缓存目录

  这些是必需的，以确保 Go 在从 Claude Desktop 运行时可以找到其模块和构建缓存。

• 使用 Docker 是最可靠的方法，因为它将所有依赖项和环境变量打包在一个容器中。

或者创建您自己的配置：

{
  "mcpServers": {
    "lokiserver": {
      "command": "path/to/loki-mcp-server",
      "args": [],
      "env": {
        "LOKI_URL": "http://localhost:3100"
      },
      "disabled": false,
      "autoApprove": ["loki_query"]
    }
  }
}

确保将 path/to/loki-mcp-server 替换为已构建的二进制文件或源代码的绝对路径。

4. 重启 Claude Desktop。

5. 您现在可以在 Claude 中使用这些工具：

   • Loki 查询示例：
     • "Query Loki for logs with the query {job="varlogs"}" (使用查询 {job="varlogs"} 查询 Loki 的日志)
     • "Find error logs from the last hour in Loki using query {job="varlogs"} |= "ERROR"" (使用查询 {job="varlogs"} |= "ERROR" 在 Loki 中查找过去一小时的错误日志)
     • "Show me the most recent 50 logs from Loki with job=varlogs" (显示我来自 Loki 的 job=varlogs 的最新 50 条日志)

与 Cursor 一起使用

您还可以将 Loki MCP 服务器与 Cursor 编辑器集成。 为此，请将以下配置添加到您的 Cursor 设置：

Docker 配置：

{
  "mcpServers": {
    "loki-mcp-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "LOKI_URL=http://host.docker.internal:3100", "loki-mcp-server:latest"]
    }
  }
}

添加此配置后，重启 Cursor，您就可以直接在编辑器中使用 Loki 查询工具。

许可证

此项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。