Victorialogs

Name: Victorialogs
Author: VictoriaMetrics-Community

本地服务

github.com/VictoriaMetrics-Community数据与分析1072 周前更新

代码仓库

关于 Victorialogs

Victorialogs 是面向使用 VictoriaLogs 的工程师和可观测性工作流的 MCP 服务。它提供只读日志及实例 API，并内置可搜索文档，支持调查与调试。

主要功能

01查询和浏览日志
02查看实例参数
03列出流、字段及其值
04获取日志统计指标
05搜索内置文档
06支持 stdio、SSE 和 Streamable HTTP

适用场景

01调查 VictoriaLogs 中的日志
02检查数据流和字段值
03查看日志统计数据
04调试时搜索文档

MCP 相关

它向 MCP 客户端提供 VictoriaLogs 只读 API 和内置文档工具，支持 stdio、SSE 和 Streamable HTTP 传输方式。

#victorialogs #mcp-server #observability

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "victoriametrics-community-mcp-victorialogs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VL_INSTANCE_ENTRYPOINT",
        "-e",
        "VL_INSTANCE_BEARER_TOKEN",
        "-e",
        "MCP_DISABLED_TOOLS",
        "ghcr.io/victoriametrics-community/mcp-victorialogs:1.8.0"
      ],
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<VL_INSTANCE_ENTRYPOINT>",
        "VL_INSTANCE_BEARER_TOKEN": "<VL_INSTANCE_BEARER_TOKEN>",
        "MCP_DISABLED_TOOLS": "<MCP_DISABLED_TOOLS>"
      }
    }
  }
}

启动命令

docker run -i --rm -e VL_INSTANCE_ENTRYPOINT -e VL_INSTANCE_BEARER_TOKEN -e MCP_DISABLED_TOOLS ghcr.io/victoriametrics-community/mcp-victorialogs:1.8.0

需要配置的环境变量

VL_INSTANCE_ENTRYPOINTURL to VictoriaMetrics instance (it should be root URL of vmlingle or vlselect), for example http://localhost:9428 or https://play-vmlogs.victoriametrics.com

VL_INSTANCE_BEARER_TOKEN密钥Authentication token for VictoriaMetrics API

MCP_DISABLED_TOOLSComma-separated list of tools to disable

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

ocighcr.io/victoriametrics-community/mcp-victorialogs:1.8.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

VictoriaLogs MCP 服务

License

这是面向 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 调用。

路线图

免责声明

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

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

贡献

欢迎为 MCP VictoriaLogs 项目贡献！

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

支持 Markdown

登录后评论

基本信息

作者: VictoriaMetrics-Community
版本: 1.8.0
传输方式: stdio
收录时间: 2025年5月14日
最近更新: 2 周前
官方 Registry: io.github.VictoriaMetrics-Community/mcp-victorialogs

报告问题

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。