mcp-victorialogs

VictoriaLogs MCP 服务

这是面向 VictoriaLogs 的 Model Context Protocol (MCP) 服务实现。

它可用于访问你的 VictoriaLogs 实例，并与 VictoriaLogs API 和文档无缝集成。 它为 VictoriaLogs 实例相关的日志、可观测性和调试任务提供全面的操作界面，并为工程师和工具提供高级自动化与交互能力。

功能

此 MCP 服务支持使用 VictoriaLogs 几乎所有只读 API，也就是 Web UI 中提供的所有功能：

• 查询日志并探索日志数据
• 显示 VictoriaLogs 实例的参数
• 列出可用的流、字段和字段值
• 以指标形式查询日志统计信息
• 在根端点提供包含设置说明和工具检查功能的 UI（仅限 Streamable HTTP 模式）

此外，MCP 服务内置了最新文档，无需联网即可搜索。

有关可用工具和提示词的详细信息，请参阅用法部分。

你可以在提示词中组合使用工具功能和文档搜索，为 VictoriaLogs 实例设计出色的使用场景。 请注意，MCP 服务及其响应的质量在很大程度上取决于客户端的能力和所用模型的质量。

你还可以将 MCP 服务与其他可观测性或文档搜索相关的 MCP 服务结合使用，获得更强大的效果。

无需安装即可试用

我们提供了一个公开可用的 VictoriaMetrics MCP 服务实例，你可以无需安装即可用它测试各项功能：

https://play-vmlogs-mcp.victoriametrics.com/mcp

注意！ 此 URL 不应用浏览器打开，而是供 MCP 客户端使用。

它以 Streamable HTTP 模式运行，并配置为与 Public VictoriaLogs Playground 配合使用。

以下是 Claude Desktop 的配置示例：

要求

• VictoriaLogs 实例：(单节点或集群)
• Go 1.26 或更高版本（如果要从源代码构建）

安装

Go

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

二进制文件

只需从 Releases 页面下载最新版本，并将其放入 PATH。

Linux x86_64 示例（另有其他架构和平台可用）：

latest=$(curl -s https://api.github.com/repos/VictoriaMetrics/mcp-victorialogs/releases/latest | grep 'tag_name' | cut -d\" -f4)
wget https://github.com/VictoriaMetrics/mcp-victorialogs/releases/download/$latest/mcp-victorialogs_Linux_x86_64.tar.gz
tar axvf mcp-victorialogs_Linux_x86_64.tar.gz

Docker

你可以使用 Docker 运行 VictoriaLogs MCP Server。

这是最快捷的入门方式，无需安装 Go 或从源代码构建。

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/mcp-victorialogs

你应将环境变量替换为自己的参数。

请注意，使用 MCP_SERVER_MODE=http 标志可启用 Streamable HTTP 模式。
有关服务模式的更多详情，请参阅配置部分。

请在 github 注册表中查看可用的 Docker 镜像。

另请参阅使用 Docker 替代二进制文件部分，了解在 stdio 模式下使用 Docker 搭配 MCP 服务客户端的更多详情。

源代码

如需从源代码构建二进制文件，可以采用以下方法：

• 克隆仓库：

  git clone https://github.com/VictoriaMetrics/mcp-victorialogs.git
  cd mcp-victorialogs
  

• 从克隆的源代码构建二进制文件：

  make build
  # after that you can find binary mcp-victorialogs and copy this file to your PATH or run inplace
  

• 从克隆的源代码构建镜像：

  docker build -t mcp-victorialogs .
  # after that you can use docker image mcp-victorialogs for running or pushing
  

Helm

如需了解使用 Helm 安装的更多详情，请参阅 VictoriaLogs MCP Server Helm chart 文档。

配置

VictoriaLogs 的 MCP 服务通过环境变量进行配置：

Variable	Description	Required	Default	Allowed values
VL_INSTANCE_ENTRYPOINT	VictoriaLogs 实例的 URL	Yes	-	-
VL_INSTANCE_BEARER_TOKEN	VictoriaLogs API 的身份验证令牌	No	-	-
VL_INSTANCE_HEADERS	随请求发送的自定义 HTTP 标头（以逗号分隔的 key=value 键值对）	No	-	-
MCP_PASSTHROUGH_HEADERS	从传入的 MCP 请求转发到 VictoriaLogs 的 HTTP 标头名称（以逗号分隔的列表）。发生冲突时优先于 VL_INSTANCE_HEADERS。仅适用于 sse/http 模式。	No	-	-
VL_DEFAULT_TENANT_ID	请求中未指定租户时使用的默认租户 ID（格式：AccountID:ProjectID 或 AccountID）	No	0:0	-
MCP_SERVER_MODE	服务运行模式。详情请参阅 Modes。	No	stdio	stdio、sse、http
MCP_LISTEN_ADDR	SSE 或 HTTP 服务的监听地址	No	localhost:8081	-
MCP_DISABLED_TOOLS	要禁用的工具列表，以逗号分隔	No	-	-
MCP_HEARTBEAT_INTERVAL	设置 streamable-http 协议的心跳间隔。 这表示 MCP 服务会通过 GET 连接向客户端发送心跳， 以防止网络基础设施（例如网关）关闭连接	No	30s	-
MCP_LOG_FORMAT	日志输出格式	No	text	text、json
MCP_LOG_LEVEL	最低日志级别	No	info	debug、info、warn、error

模式

MCP 服务支持以下运行模式（传输方式）：

• stdio - 标准输入/输出模式，服务从标准输入读取命令，并将响应写入标准输出。这是默认模式，适用于本地服务。
• sse - Server-Sent Events。服务将开放 /sse 和 /message 端点，用于 SSE 连接。
• http - Streamable HTTP。服务将开放 /mcp 端点，用于 HTTP 连接。

有关传输方式的更多信息，请参阅 MCP 文档：

• 核心概念 -> 传输方式
• 规范 -> 传输方式

Сonfiguration examples

# For a public playground
export VL_INSTANCE_ENTRYPOINT="https://play-vmlogs.victoriametrics.com"

# Custom headers for authentication (e.g., behind a reverse proxy)
# Expected syntax is key=value separated by commas
export VL_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"

# Forward specific headers from incoming MCP requests to VictoriaLogs
export MCP_PASSTHROUGH_HEADERS="X-Token,X-Access-Key"

# Server mode
export MCP_SERVER_MODE="sse"
export MCP_SSE_ADDR="0.0.0.0:8081"
export MCP_DISABLED_TOOLS="hits,facets"

端点

在 SSE 和 HTTP 模式下，MCP 服务提供以下端点：

Endpoint	Description
/	帮助进行设置和检查工具的首页（仅限 HTTP 模式）
/sse + /message	SSE 模式下用于传递消息的端点（适用于支持 SSE 的 MCP 客户端）
/mcp	HTTP 模式下用于流式传递消息的 HTTP 端点（适用于支持 Streamable HTTP 的 MCP 客户端）
/metrics	Prometheus 格式的指标，用于监控 MCP 服务
/health/liveness	存活检查端点，用于确认服务正在运行
/health/readiness	就绪检查端点，用于确认服务已准备好接受请求

在客户端中设置

Cursor

前往：Settings -> Cursor Settings -> MCP -> Add new global MCP server，并将以下配置粘贴到 Cursor 的 ~/.cursor/mcp.json 文件中：

{
  "mcpServers": {
    "victorialogs": {
      "command": "/path/to/mcp-victorialogs",
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

更多信息请参阅 Cursor MCP 文档。

Claude Desktop

将以下内容添加到 Claude Desktop 的 claude_desktop_config.json 文件中（打开 Settings -> Developer -> Edit config 即可找到该文件）：

{
  "mcpServers": {
    "victorialogs": {
      "command": "/path/to/mcp-victorialogs",
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

更多信息请参阅 Claude Desktop MCP 文档。

Claude Code

运行命令：

claude mcp add victorialogs -- /path/to/mcp-victorialogs \
  -e VL_INSTANCE_ENTRYPOINT=<YOUR_VL_INSTANCE> \
  -e VL_INSTANCE_BEARER_TOKEN=<YOUR_VL_BEARER_TOKEN> \
  -e VL_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"

更多信息请参阅 Claude Code MCP 文档。

Codex

Codex CLI 和 IDE 扩展使用相同的 MCP 配置文件：~/.codex/config.toml （也可以使用受信任项目中的 .codex/config.toml）。

运行命令：

codex mcp add victorialogs \
  --env VL_INSTANCE_ENTRYPOINT=<YOUR_VL_INSTANCE> \
  --env VL_INSTANCE_BEARER_TOKEN=<YOUR_VL_BEARER_TOKEN> \
  --env VL_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>" \
  -- /path/to/mcp-victorialogs

或者将以下内容添加到 Codex 的 ~/.codex/config.toml 文件中：

[mcp_servers.victorialogs]
command = "/path/to/mcp-victorialogs"

[mcp_servers.victorialogs.env]
VL_INSTANCE_ENTRYPOINT = "<YOUR_VL_INSTANCE>"
VL_INSTANCE_BEARER_TOKEN = "<YOUR_VL_BEARER_TOKEN>"
VL_INSTANCE_HEADERS = "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"

如果以 Streamable HTTP 模式运行服务，可以使用以下命令注册：

codex mcp add victorialogs --url http://localhost:8081/mcp

更多信息请参阅 Codex MCP 文档。

Visual Studio Code

将以下内容添加到 VS Code MCP 配置文件中：

{
  "servers": {
    "victorialogs": {
      "type": "stdio",
      "command": "/path/to/mcp-victorialogs",
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

更多信息请参阅 VS Code MCP 文档。

Zed

将以下内容添加到 Zed 配置文件中：

  "context_servers": {
    "victorialogs": {
      "command": {
        "path": "/path/to/mcp-victorialogs",
        "args": [],
        "env": {
                  "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
      },
      "settings": {}
    }
  }
}

更多信息请参阅 Zed MCP 文档。

JetBrains IDEs

• 打开 Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP)。
• 点击 Add (+)
• 选择 As JSON
• 将以下内容填入输入框：

{
  "mcpServers": {
    "victorialogs": {
      "command": "/path/to/mcp-victorialogs",
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

Windsurf

将以下内容添加到 Windsurf MCP 配置文件中。

{
  "mcpServers": {
    "victorialogs": {
      "command": "/path/to/mcp-victorialogs",
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

更多信息请参阅 Windsurf MCP 文档。

使用 Docker 替代二进制文件

你可以使用 Docker 运行 VictoriaLogs MCP Server，而不是使用本地二进制文件。

请按以下方式替换上文配置示例中的运行命令：

{
  "mcpServers": {
    "victorialogs": {
      "command": "docker",
        "args": [
          "run",
          "-i", "--rm",
          "-e", "VL_INSTANCE_ENTRYPOINT",
          "-e", "VL_INSTANCE_BEARER_TOKEN",
          "-e", "VL_INSTANCE_HEADERS",
          "ghcr.io/victoriametrics/mcp-victorialogs",
        ],
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

用法

安装并配置 MCP 服务后，你就可以使用喜爱的 MCP 客户端开始使用它。

你可以从以下短语开始与 AI 助手对话：

Use MCP VictoriaLogs in the following answers

不过这并非必需，你可以直接开始提问，助手会自动使用工具和文档，为你提供最佳答案。

工具集

MCP VictoriaLogs 提供了众多工具，可用于与 VictoriaLogs 实例交互。

以下是可用工具列表：

工具	描述
documentation	搜索内置的 VictoriaLogs 文档
facets	每个日志字段中出现频率最高的值
field_names	列出查询的字段名称
field_values	列出查询的字段值
flags	查看 VictoriaLogs 实例的非默认标志
hits	按存储桶分组的匹配日志条目数
query	执行 LogsQL 查询
stats_query	查询给定时间的日志统计信息
stats_query_range	查询给定时间范围内的日志统计信息
stream_field_names	列出查询的流字段
stream_field_values	列出查询的流字段值
stream_ids	列出查询的流 ID
streams	列出查询的流

提示词

该服务包含用于常见任务的预定义提示词。

目前这些只是示例，提示词库今后还会扩充：

提示词	描述
documentation	搜索 VictoriaLogs 文档中的特定主题

常见问题

为什么 MCP 服务使用的资源比简单 API 代理预期的更多？

该服务为 documentation 工具内置了一个包含 VictoriaMetrics 文档和博客文章的向量数据库。 它可以帮助回答有关 VictoriaLogs 的复杂问题，而无需向大模型提供所有数据。
这是资源占用的主要来源。若要减少资源占用，请将 documentation 添加到 MCP_DISABLED_TOOLS 环境变量，以完全禁用向量数据库加载。

如何让一个 MCP 服务实例用于多个 VictoriaMetrics 实例？

你可以在 MCP Server 中使用 MCP_PASSTHROUGH_HEADERS 参数，结合 vmauth 中基于标头的路由，根据 MCP 客户端配置中的 HTTP 标头值，在多个实例之间路由 MCP 调用。

路线图

• 支持“解释查询”工具
• 支持与 VictoriaMetrics Cloud 的可选集成
• 除当前的文档工具外，为服务添加一些额外知识：
  • VictoriaMetrics 博客文章
  • Github 问题
  • 公共 Slack 聊天记录
  • CRD 架构
• 实现多租户版本的 MCP（支持多个部署）
• 添加标志/配置验证工具
• 通过配置启用/禁用工具

免责声明

此类 MCP 服务以及 AI 服务和 Agent 无法保证结果的准确性、完整性和可靠性。 你应仔细核实 AI 得出的结果。

MCP Server 的质量及其响应很大程度上取决于客户端的能力和所用模型的质量。

贡献

欢迎为 MCP VictoriaLogs 项目贡献！

欢迎提交问题、功能请求或拉取请求。