Loki MCP Server

Loki MCP 服务

基于 Go 的 Model Context Protocol（MCP）服务实现，集成了 Grafana Loki。

开始使用

先决条件

• Go 1.16 或更高版本

构建和运行

构建并运行服务：

# Build the server
go build -o loki-mcp-server ./cmd/server

# Run the server
./loki-mcp-server

或者直接使用 Go 运行：

go run ./cmd/server

该服务遵循 Model Context Protocol（MCP），通过 stdin/stdout 和 SSE 进行通信。因此，它适用于 Claude Desktop 和其他兼容 MCP 的客户端。

项目结构

.
├── cmd/
│   ├── server/       # MCP server implementation
│   └── client/       # Client for testing the MCP server
├── internal/
│   ├── handlers/     # Tool handlers
│   └── models/       # Data models
├── pkg/
│   └── utils/        # Utility functions and shared code
└── go.mod            # Go module definition

MCP 服务

Loki MCP 服务实现了 Model Context Protocol（MCP），并提供以下工具：

Loki 查询工具

loki_query 工具可用于查询 Grafana Loki 日志数据：

• 必需参数：

  • query：LogQL 查询字符串

• 可选参数：

  • url：Loki 服务 URL（默认值：取自 LOKI_URL 环境变量或 http://localhost:3100）
  • start：查询开始时间（默认值：1h 前）
  • end：查询结束时间（默认值：现在）
  • limit：要返回的最大条目数（默认值：100）
  • org：查询的组织 ID（作为 X-Scope-OrgID 标头发送）

环境变量

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

• LOKI_URL：请求中未指定时使用的默认 Loki 服务 URL
• LOKI_ORG_ID：请求中未指定时使用的默认组织 ID
• LOKI_USERNAME：请求中未指定时用于基本身份验证的默认用户名
• LOKI_PASSWORD：请求中未指定时用于基本身份验证的默认密码
• LOKI_TOKEN：请求中未指定时用于身份验证的默认 bearer token

安全提示：使用身份验证环境变量时，请注意不要在日志或配置文件中泄露敏感凭据。条件允许时，请考虑使用基于 token 的身份验证，而不是用户名/密码。

测试 MCP 服务

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

# Build the client
go build -o loki-mcp-client ./cmd/client

# Loki query examples:
./loki-mcp-client loki_query "{job=\"varlogs\"}"
./loki-mcp-client loki_query "{job=\"varlogs\"}" "-1h" "now" 100

# Using environment variables:
export LOKI_URL="http://localhost:3100"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables for both URL and org:
export LOKI_URL="http://localhost:3100"
export LOKI_ORG_ID="tenant-123"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables for authentication:
export LOKI_URL="http://localhost:3100"
export LOKI_USERNAME="admin"
export LOKI_PASSWORD="password"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables with bearer token:
export LOKI_URL="http://localhost:3100"
export LOKI_TOKEN="your-bearer-token"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using all environment variables together:
export LOKI_URL="http://localhost:3100"
export LOKI_ORG_ID="tenant-123"
export LOKI_USERNAME="admin"
export LOKI_PASSWORD="password"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using org parameter for multi-tenant setups:
./loki-mcp-client loki_query "{job=\"varlogs\"}" "" "" "" "" "" "tenant-123"

Docker 支持

你可以使用 Docker 构建并运行 MCP 服务：

# Build the Docker image
docker build -t loki-mcp-server .

# Run the server
docker run --rm -i loki-mcp-server

或者，你可以使用 Docker Compose：

# Build and run with 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. 使用提供的测试脚本查询日志：

   # Run with default parameters (queries last 15 minutes of logs)
   ./test-loki-query.sh
   
   # Query for error logs
   ./test-loki-query.sh '{job="varlogs"} |= "ERROR"'
   
   # Specify a custom time range and limit
   ./test-loki-query.sh '{job="varlogs"}' '-1h' 'now' 50
   

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

   # Insert 10 dummy logs with default settings
   ./insert-loki-logs.sh
   
   # Insert 20 logs with custom job and app name
   ./insert-loki-logs.sh --num 20 --job "custom-job" --app "my-app"
   
   # Insert logs with custom environment and interval
   ./insert-loki-logs.sh --env "production" --interval 0.5
   
   # Show help message
   ./insert-loki-logs.sh --help
   

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

服务器发送事件（SSE）支持

该服务现在支持两种通信模式：

1. 遵循 Model Context Protocol（MCP）的标准输入/输出（stdin/stdout）
2. 带有服务器发送事件（SSE）端点的 HTTP 服务，可与 n8n 等工具集成

HTTP 服务的默认端口为 8080，但可以使用 SSE_PORT 环境变量进行配置。

服务端点

以 HTTP 模式运行时，该服务会公开以下端点：

• SSE 端点：http://localhost:8080/sse - 用于实时事件流
• MCP 端点：http://localhost:8080/mcp - 用于 MCP 协议消息传递

使用 Docker 和 SSE

使用 Docker 运行服务时，请确保公开端口 8080：

# Build the Docker image
docker build -t loki-mcp-server .

# Run the server with port mapping
docker run -p 8080:8080 --rm -i loki-mcp-server

n8n 集成

你可以将 Loki MCP Server 集成到 n8n 工作流中：

1. 在 n8n 中安装 MCP Client Tools 节点

2. 使用以下参数配置节点：

   • SSE 端点：http://your-server-address:8080/sse（替换为你的实际服务地址）
   • 身份验证：如果需要，请选择适当的身份验证方式
   • 要包含的工具：选择要向 AI Agent 开放的 Loki 工具

3. 将 MCP Client Tool 节点连接到使用 Loki 查询功能的 AI Agent 节点

工作流示例： 触发器 → MCP Client Tool（Loki 服务）→ AI Agent（Claude）

架构

Loki MCP Server 采用模块化架构：

• 服务端：位于 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 的示例（最可靠）

注意：

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

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

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

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

或者创建你自己的配置：

{
  "mcpServers": {
    "lokiserver": {
      "command": "path/to/loki-mcp-server",
      "args": [],
      "env": {
        "LOKI_URL": "http://localhost:3100",
        "LOKI_ORG_ID": "your-default-org-id",
        "LOKI_USERNAME": "your-username",
        "LOKI_PASSWORD": "your-password",
        "LOKI_TOKEN": "your-bearer-token"
      },
      "disabled": false,
      "autoApprove": ["loki_query"]
    }
  }
}

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

4. 重启 Claude Desktop。

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

   • Loki 查询示例：
     • “使用查询 {job="varlogs"} 查询 Loki 日志”
     • “使用查询 {job="varlogs"} |= "ERROR" 查找 Loki 中过去一小时的错误日志”
     • “显示 Loki 中 job=varlogs 的最新 50 条日志”
     • “使用查询 {job="varlogs"} 查询 org 为 'tenant-123' 的 Loki 日志”

在自然语言提示词中使用组织 ID

在 Claude Desktop 或其他 AI 助手中使用此 MCP 服务时，用户可以通过多种方式在提示词中自然地提及组织 ID：

直接提及组织

• “查询组织 'tenant-123' 的 Loki 日志，查询语句为 {job="varlogs"}”
• “使用 {job="web"} 搜索 org 为 'production-env' 的 Loki 日志”
• “获取与 {service="api"} 匹配的组织 ID 为 'client-abc' 的日志”

上下文组织提及

• “使用查询 {level="error"} 检查我们生产租户的错误日志（组织：prod-001）”
• “查找过去一小时内客户组织 ‘customer-xyz’ 的所有日志”
• “使用组织租户 tenant-456 查询 Loki，查找与 {job="backend"} 匹配的日志”

多租户场景

• “切换到组织 ‘dev-team’，并查询 {job="logs"} 以进行调试”
• “使用组织 ‘staging-env’ 搜索过去 2 小时内的警告日志”
• “在租户 ‘qa-environment’ 中搜索所有错误消息”

与其他参数结合使用

• “查询组织 ‘prod-cluster’ 从 2 小时前到现在的 Loki 日志，数量限制为 50 条”
• “获取组织 ‘microservice-team’ 中与查询 {app="payment"} 匹配的最后 100 条日志”

提及这些自然语言提示词中的任何一个时，AI 助手都会自动将“organization”、“org”、“tenant”或“organization ID”等词映射到 Loki 查询工具中的 org 参数，并将其作为 X-Scope-OrgID 标头发送到 Loki 服务，以正确筛选多租户数据。

关键是在请求中自然地提及任何具体参数——AI 会理解如何将其映射到相应的 Loki 查询工具参数。如果没有明确提及参数，系统会自动使用环境变量中的默认值：

• LOKI_URL：Loki 服务 URL
• LOKI_ORG_ID：组织 ID
• LOKI_USERNAME 和 LOKI_PASSWORD：基本身份验证凭据
• LOKI_TOKEN：Bearer 令牌身份验证凭据

这样就可以很方便地一次性设置默认连接参数，之后使用自然语言查询，而无需每次都指定身份验证详细信息。

在 Cursor 中使用

你也可以将 Loki MCP 服务集成到 Cursor 编辑器中。为此，请将以下配置添加到 Cursor 设置中：

Docker 配置：

{
  "mcpServers": {
    "loki-mcp-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "LOKI_URL=http://host.docker.internal:3100", 
               "-e", "LOKI_ORG_ID=your-default-org-id",
               "-e", "LOKI_USERNAME=your-username",
               "-e", "LOKI_PASSWORD=your-password",
               "-e", "LOKI_TOKEN=your-bearer-token",
               "loki-mcp-server:latest"]
    }
  }
}

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

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

运行测试

项目包含全面的单元测试和 CI/CD 工作流，以确保可靠性：

# Run all tests
go test ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# Run tests with race detection  
go test -race ./...