loki MCP

洛基MCP服务器


基于Go语言的模型上下文协议（MCP）服务器实现，与Grafana-Loki集成。

入门指南

先决条件

• 上涨1.16或更高

建立和运行

构建并运行服务器：

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

# Run the server
./loki-mcp-server

或者直接用Go运行：

go run ./cmd/server

服务器按照模型上下文协议（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服务器实现了模型上下文协议（MCP），并提供了以下工具：

洛基查询工具

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

• 所需参数：

- query：LogQL查询字符串

• 可选参数：

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

环境变量

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

• LOKI_URL：如果请求中未指定，则使用默认的Loki服务器URL
• LOKI_ORG_ID：如果请求中未指定，则使用默认组织ID
• LOKI_USERNAME：如果请求中未指定基本身份验证的默认用户名
• LOKI_PASSWORD：如果请求中未指定基本身份验证的默认密码
• LOKI_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发送示例日志的日志生成器容器 - 洛基MCP服务器

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

   # 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

1. 插入虚拟日志进行测试：

   # 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

1. 访问Grafana用户界面http://localhost:3000直观地探索日志。

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

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

1. 遵循模型上下文协议（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集成

您可以将洛基MCP服务器与n8n工作流集成：

1. 在n8n中安装MCP客户端工具节点

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

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

1. 将MCP客户端工具节点连接到将使用Loki查询功能的AI代理节点

工作流程示例： 触发→ MCP客户端工具（洛基服务器）→ 人工智能代理（克劳德）

建筑

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

• 服务器：中的主要MCP服务器实现 cmd/server/main.go
• 客户端：中的测试客户端 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

1. 使用以下命令将配置添加到Claude Desktop配置文件中 claude_desktop_config_binary.json.

选项2：使用带有Shell脚本的Go Run

1. 使脚本可执行：

chmod +x run-mcp-server.sh

1. 使用以下命令将配置添加到Claude Desktop配置文件中 claude_desktop_config_script.json.

选项3：使用Docker（推荐）

1. 构建Docker镜像：

docker build -t loki-mcp-server .

1. 使用以下命令将配置添加到Claude Desktop配置文件中 claude_desktop_config_docker.json.

配置详情

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：用户的主目录 - 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",
        "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 具有构建二进制或源代码的绝对路径。

1. 重新启动克劳德桌面。

1. 您现在可以使用Claude中的工具：

- Loki查询示例： - “使用查询｛job=”varlogs“｝向Loki查询日志” - 使用查询{job=“varlogs”}|=“error”在Loki中查找过去一小时的错误日志 - “显示来自Loki的最近50条job=varlogs日志” - “使用查询｛job=”varlogs“｝向洛基查询组织为'tenant-123'的日志”

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

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

直接组织参考

• “使用查询｛job=”varlogs“｝向Loki查询来自组织'tenant-123'的日志”
• 使用{job=“web”}在洛基日志中搜索组织“生产环境”
• “从匹配{service=”api“}的组织ID'client-abc'获取日志”

上下文组织提及

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

多租户场景

• 切换到组织“开发团队”并查询｛job=“logs”｝进行调试
• “使用org'staging env'搜索过去2小时内的警告日志”
• “在租户'qa环境'中搜索日志以查找任何错误消息”

结合其他参数

• “查询Loki从2小时前到现在的组织'prod cluster'，限制为50”
• “从组织‘微服务团队’获取查询{app=“payment”}的最后100条日志”

当你提到这些自然语言提示中的任何一个时，人工智能助手会自动将“组织”、“org”、“租户”或“组织ID”等术语映射到 org Loki查询工具中的参数，作为 X-Scope-OrgID 将标头发送到您的Loki服务器，以进行适当的多租户过滤。

关键是在你的请求中自然地提到任何特定的参数——人工智能将理解如何将它们映射到适当的洛基查询工具参数。当参数没有明确提及时，系统将自动使用环境变量的默认值：

• LOKI_URL 对于Loki服务器URL
• LOKI_ORG_ID 对于组织ID
• LOKI_USERNAME 和 LOKI_PASSWORD 用于基本身份验证
• LOKI_TOKEN 用于承载令牌身份验证

这使得设置默认连接参数一次，然后使用自然语言查询非常方便，而不必每次都指定身份验证详细信息。

与光标一起使用

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

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许可证获得许可-有关详细信息，请参阅许可证文件。

运行测试

该项目包括全面的单元测试和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 ./...