洛基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 definitionMCP服务器
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服务器URLLOKI_ORG_ID：如果请求中未指定，则使用默认组织IDLOKI_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查询：
- 启动Docker Compose环境：
docker-compose up -d这将开始：
- 端口3100上的Loki服务器 - 端口3000上的Grafana实例（预先配置了Loki作为数据源） - 向Loki发送示例日志的日志生成器容器 - 洛基MCP服务器
- 使用提供的测试脚本查询日志：
# 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- 插入虚拟日志进行测试：
# 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- 访问Grafana用户界面http://localhost:3000直观地探索日志。
服务器发送事件（SSE）支持
服务器现在支持两种通信模式：
- 遵循模型上下文协议（MCP）的标准输入/输出（stdin/stdout）
- 带有服务器发送事件（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-servern8n集成
您可以将洛基MCP服务器与n8n工作流集成：
- 在n8n中安装MCP客户端工具节点
- 使用以下参数配置节点：
- SSE端点: http://your-server-address:8080/sse （替换为您的实际服务器地址） - 认证：如果需要，请选择适当的身份验证 - 要包含的工具：选择要向AI Agent公开的Loki工具
- 将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：使用编译的二进制文件
- 构建服务器：
go build -o loki-mcp-server ./cmd/server- 使用以下命令将配置添加到Claude Desktop配置文件中
claude_desktop_config_binary.json.
选项2：使用带有Shell脚本的Go Run
- 使脚本可执行：
chmod +x run-mcp-server.sh- 使用以下命令将配置添加到Claude Desktop配置文件中
claude_desktop_config_script.json.
选项3：使用Docker（推荐）
- 构建Docker镜像：
docker build -t loki-mcp-server .- 使用以下命令将配置添加到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 具有构建二进制或源代码的绝对路径。
- 重新启动克劳德桌面。
- 您现在可以使用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服务器URLLOKI_ORG_ID对于组织IDLOKI_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 ./...