项目简介

'mcp-victorialogs' 是 VictoriaLogs 的 Model Context Protocol (MCP) 服务器实现。它旨在将您的 VictoriaLogs 实例与支持 MCP 协议的大语言模型（LLM）客户端无缝集成，从而提供强大的日志查询、分析和自动化能力。通过此服务器，LLM 客户端可以访问 VictoriaLogs 的 API 和内嵌文档，实现更智能的日志监控、调试和可观测性任务。

主要功能点

日志查询与探索: 允许通过 LLM 客户端执行 LogsQL 查询，探索日志数据。
实例信息查看: 查看 VictoriaLogs 实例的各种参数和配置。
流与字段管理: 列出可用的日志流、字段名称及其值。
日志统计: 将日志数据作为指标进行查询，获取统计信息。
离线文档搜索: 内嵌最新的 VictoriaLogs 文档，支持离线搜索相关内容。

安装步骤

该服务器可以通过多种方式安装和运行：

使用 Go 安装: 如果您已安装 Go 1.24 或更高版本，可以直接运行以下命令安装：

go install github.com/VictoriaMetrics-Community/mcp-victorialogs/cmd/mcp-victorialogs@latest

安装完成后，'mcp-victorialogs' 可执行文件将位于您的 Go 二进制路径下。

下载预编译二进制文件: 从项目的 Releases 页面下载适用于您操作系统的最新预编译二进制文件。下载后，解压并将其放置在您的系统 PATH 路径下，以便可以直接通过命令行运行。

使用 Docker 运行: 最简单的启动方式是使用 Docker。运行以下命令，请根据您的 VictoriaLogs 实例信息替换 'VL_INSTANCE_ENTRYPOINT' 环境变量。此示例以 HTTP 模式运行在端口 8081：

docker run -d --name mcp-victorialogs \
  -e VL_INSTANCE_ENTRYPOINT=https://play-vmlogs.victoriametrics.com \
  -e MCP_SERVER_MODE=http \
  -e MCP_LISTEN_ADDR=:8081 \
  -p 8081:8081 \
  ghcr.io/victoriametrics-community/mcp-victorialogs

您可以在 GitHub Registry 查看可用的 Docker 镜像。

从源代码构建: 克隆仓库后，进入项目目录，然后运行 'make build' 命令即可构建二进制文件。

服务器配置

MCP 客户端需要配置 MCP 服务器的启动方式和必要的参数。以下是关键的配置信息：

服务器名称 (Server Name): 您在 MCP 客户端中为该服务器选择的唯一名称，例如 'victorialogs'。
启动命令 (Command): 用于启动 MCP 服务器的命令行指令。
- 如果您通过 Go 或下载二进制文件安装，命令通常是 '/path/to/mcp-victorialogs'。
- 如果您使用 Docker 运行，命令通常是 'docker'，并且需要额外的参数（'args'）来指示 Docker 如何运行镜像。
环境变量 (Environment Variables): 用于配置 'mcp-victorialogs' 服务器如何连接 VictoriaLogs 实例及其运行模式。这些环境变量需要作为参数传递给启动命令。
- 'VL_INSTANCE_ENTRYPOINT': 必需。您的 VictoriaLogs 实例的 URL，例如 'https://play-vmlogs.victoriametrics.com'。
- 'VL_INSTANCE_BEARER_TOKEN': 可选。用于 VictoriaLogs API 认证的 Bearer Token。
- 'VL_INSTANCE_HEADERS': 可选。自定义 HTTP 头，以逗号分隔的 'key=value' 形式提供，例如 'HEADER1=VALUE1,HEADER2=VALUE2'。
- 'MCP_SERVER_MODE': 可选。服务器运行模式，默认为 'stdio'。可设置为 'stdio' (标准输入输出，适用于本地客户端)、'sse' (Server-Sent Events) 或 'http' (Streamable HTTP)。
- 'MCP_LISTEN_ADDR': 可选。当 'MCP_SERVER_MODE' 为 'sse' 或 'http' 时，服务器监听的地址和端口，默认为 'localhost:8081'。

MCP客户端配置参数示例

不同的 MCP 客户端有不同的配置界面或文件格式。以下是一个常见的 JSON 配置结构示例，展示了上述参数如何映射到客户端配置中。您无需手动编写此 JSON，只需在客户端的配置界面中填入相应的参数值即可。

{
  "mcpServers": {
    "victorialogs": { // 您为MCP服务器选择的名称
      "command": "/path/to/mcp-victorialogs", // MCP服务器可执行文件的完整路径
      "env": { // 传递给MCP服务器的环境变量
        "VL_INSTANCE_ENTRYPOINT": "<您的_VICTORIALOGS_实例_URL>", // 例如: "https://play-vmlogs.victoriametrics.com"
        "VL_INSTANCE_BEARER_TOKEN": "<您的_认证_TOKEN>", // 可选, 您的Bearer认证Token
        "VL_INSTANCE_HEADERS": "<HEADER_KEY>=<HEADER_VALUE>" // 可选, 额外的HTTP请求头
      }
    }
  }
}

基本使用方法

安装并配置: 按照上述步骤安装 'mcp-victorialogs' 服务器，并根据您使用的 MCP 客户端（如 Cursor, Claude Desktop, VS Code, Zed 等）的指引，将服务器名称、启动命令及环境变量配置到客户端中。
启动对话: 在您的 AI 助手客户端中，一旦 MCP 服务器被客户端识别并激活，您可以直接开始提问。有时，明确提及 "使用 MCP VictoriaLogs" 可以帮助 AI 助手更好地理解并调用该服务器的功能。
提问示例:
- "查询过去一小时内所有包含 'error' 关键字的日志。"
- "显示 VictoriaLogs 实例的所有非默认配置参数。"
- "列出所有可用的日志流和字段。"
- "搜索文档中关于 'LogsQL' 的内容。"
- "计算最近24小时内日志错误的总数。"

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息