mcp-victoriatraces

Name: mcp-victoriatraces
Author: VictoriaMetrics-Community

本地服务

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

代码仓库

关于 mcp-victoriatraces

mcp-victoriatraces 为工程师和工具提供访问 VictoriaTraces 实例的 MCP 接口，用于追踪分析和可观测性工作。它结合以只读为主的 API 访问与可离线搜索的内置文档。

主要功能

01列出已追踪的服务和操作
02查询追踪并检查追踪 ID
03查看服务依赖关系
04离线搜索内置文档

适用场景

01探索某项服务的追踪数据
02按追踪 ID 检查追踪详情
03查看服务间的依赖关系
04离线查阅 VictoriaTraces 文档

MCP 相关

该 MCP 服务提供访问 VictoriaTraces API 的工具，可查询服务、操作、追踪和依赖关系，并提供文档搜索工具与提示词。它支持 stdio、SSE 和 Streamable HTTP 模式。

配置

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

mcp.json · 通用配置

{
  "mcpServers": {
    "victoriametrics-community-mcp-victoriatraces": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VT_INSTANCE_ENTRYPOINT",
        "-e",
        "VT_INSTANCE_BEARER_TOKEN",
        "-e",
        "MCP_DISABLED_TOOLS",
        "ghcr.io/victoriametrics-community/mcp-victoriatraces:1.5.0"
      ],
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<VT_INSTANCE_ENTRYPOINT>",
        "VT_INSTANCE_BEARER_TOKEN": "<VT_INSTANCE_BEARER_TOKEN>",
        "MCP_DISABLED_TOOLS": "<MCP_DISABLED_TOOLS>"
      }
    }
  }
}

启动命令

docker run -i --rm -e VT_INSTANCE_ENTRYPOINT -e VT_INSTANCE_BEARER_TOKEN -e MCP_DISABLED_TOOLS ghcr.io/victoriametrics-community/mcp-victoriatraces:1.5.0

需要配置的环境变量

VT_INSTANCE_ENTRYPOINTURL to VictoriaTraces instance (it should be root URL of vtlingle or vtselect), for example http://localhost:10428

VT_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-victoriatraces:1.5.0stdio

工具

还没有获取到工具列表

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

详细介绍

VictoriaTraces MCP 服务

License

这是为 VictoriaTraces 实现的 Model Context Protocol (MCP) 服务。

它可访问你的 VictoriaTraces 实例，并与 VictoriaTraces API 和文档无缝集成。它为与 VictoriaTraces 实例相关的跟踪、可观测性和调试任务提供全面的接口，并为工程师和工具提供高级自动化与交互能力。

功能

此 MCP 服务可让你使用 VictoriaTraces 几乎所有只读 API：

获取服务和操作（Span 名称）
查询跟踪数据，探索和分析跟踪数据

此外，MCP 服务还内嵌了最新文档，并能在离线情况下搜索文档。

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

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

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

要求

VictoriaTraces 实例：单节点或集群
Go 1.25 或更高版本（如果你想从源代码构建）

安装

Go

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

二进制文件

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

Linux x86_64 示例（也提供其他架构和平台版本）：

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

Docker

你可以使用 Docker 运行 VictoriaTraces MCP 服务。

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

docker run -d --name mcp-victoriatraces \
  -e VT_INSTANCE_ENTRYPOINT=https://localhost:10428 \
  -e MCP_SERVER_MODE=http \
  -e MCP_LISTEN_ADDR=:8081 \
  -p 8081:8081 \
  ghcr.io/victoriametrics-community/mcp-victoriatraces

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

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

请查看 github registry中的可用 Docker 镜像。

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

源代码

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

克隆仓库：

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

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

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

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

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

Helm

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

配置

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

变量	描述	必填	默认值	允许的值
`VT_INSTANCE_ENTRYPOINT`	VictoriaTraces 实例的 URL	是	-	-
`VT_INSTANCE_BEARER_TOKEN`	VictoriaTraces API 的身份验证令牌	否	-	-
`VT_INSTANCE_HEADERS`	随请求发送的自定义 HTTP 标头（以逗号分隔的 key=value 对）	否	-	-
`VT_DEFAULT_TENANT_ID`	请求中未指定租户时使用的默认租户 ID（格式：`AccountID:ProjectID` 或 `AccountID`）	否	`0:0`	-
`MCP_SERVER_MODE`	服务运行模式。详情请参阅模式。	否	`stdio`	`stdio`、`sse`、`http`
`MCP_LISTEN_ADDR`	SSE 或 HTTP 服务的监听地址	否	`localhost:8081`	-
`MCP_DISABLED_TOOLS`	要禁用的工具列表，以逗号分隔	否	-	-
`MCP_HEARTBEAT_INTERVAL`	定义 streamable-http 协议的心跳间隔。这意味着 MCP 服务会通过 GET 连接向客户端发送心跳，以防止网络基础设施（例如网关）关闭连接，从而保持连接有效	否	`30s`	-
`MCP_LOG_FORMAT`	日志输出格式	否	`text`	`text`、`json`
`MCP_LOG_LEVEL`	最低日志级别	否	`info`	`debug`、`info`、`warn`、`error`

模式

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

stdio - 标准输入/输出模式，服务从标准输入读取命令，并将响应写入标准输出。这是默认模式，适用于本地服务。
sse - 服务器发送事件。服务将开放 /sse 和 /message 端点，用于 SSE 连接。
http - 可流式传输的 HTTP。服务将开放 /mcp 端点，用于 HTTP 连接。

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

配置示例

export VT_INSTANCE_ENTRYPOINT="https://localhost:10428"

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

# Server mode
export MCP_SERVER_MODE="sse"
export MCP_SSE_ADDR="0.0.0.0:8082"

端点

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

端点	说明
`/sse` + `/message`	SSE 模式下的消息端点（适用于支持 SSE 的 MCP 客户端）
`/mcp`	HTTP 模式下用于流式传输消息的 HTTP 端点（适用于支持可流式传输 HTTP 的 MCP 客户端）
`/metrics`	Prometheus 格式的指标，用于监控 MCP 服务
`/health/liveness`	存活检查端点，用于确认服务正在运行
`/health/readiness`	就绪检查端点，用于确认服务已准备好接收请求

在客户端中配置

Cursor

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

{
  "mcpServers": {
    "victoriatraces": {
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

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

Claude Desktop

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

{
  "mcpServers": {
    "victoriatraces": {
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

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

Claude Code

运行以下命令：

claude mcp add victoriatraces -- /path/to/mcp-victoriatraces \
  -e VT_INSTANCE_ENTRYPOINT=<YOUR_VT_INSTANCE> \
  -e VT_INSTANCE_BEARER_TOKEN=<YOUR_VT_BEARER_TOKEN> \
  -e VT_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"

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

Visual Studio Code

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

{
  "servers": {
    "victoriatraces": {
      "type": "stdio",
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

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

Zed

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

  "context_servers": {
    "victoriatraces": {
      "command": {
        "path": "/path/to/mcp-victoriatraces",
        "args": [],
        "env": {
          "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
          "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
          "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
        }
      },
      "settings": {}
    }
  }
}

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

JetBrains IDE

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

{
  "mcpServers": {
    "victoriatraces": {
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

Windsurf

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

{
  "mcpServers": {
    "victoriatraces": {
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

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

使用 Docker 替代二进制文件

你可以使用 Docker 运行 VictoriaTraces MCP Server，替代本地二进制文件。

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

{
  "mcpServers": {
    "victoriatraces": {
      "command": "docker",
        "args": [
          "run",
          "-i", "--rm",
          "-e", "VT_INSTANCE_ENTRYPOINT",
          "-e", "VT_INSTANCE_BEARER_TOKEN",
          "-e", "VT_INSTANCE_HEADERS",
          "ghcr.io/victoriametrics-community/mcp-victoriatraces",
        ],
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

使用方法

安装并配置 MCP 服务后，即可使用你喜欢的 MCP 客户端。

你可以用下面这句话开始与 AI 助手对话：

Use MCP VictoriaTraces in the following answers

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

工具集

MCP VictoriaTraces 提供了许多用于与您的 VictoriaTraces 实例交互的工具。

以下是可用工具列表：

工具	描述
`documentation`	搜索内置的 VictoriaTraces 文档
`services`	列出所有被追踪的服务
`service_names`	获取某个服务的所有 Span 名称（操作）
`traces`	查询 Trace
`trace`	根据 Trace ID 获取 Trace 信息
`dependencies`	查询服务依赖关系图

提示词

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

目前这些只是示例，未来会扩充提示词库：

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

路线图

实现多租户版本的 MCP（支持多个部署）
在此功能发布后添加服务图工具（参见该 PR）

免责声明

此类 AI 服务和 Agent，以及 MCP 服务，均无法保证结果的准确性、完整性和可靠性。请务必仔细核查 AI 得出的结果。

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

贡献

欢迎为 MCP VictoriaTraces 项目做出贡献！

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

支持 Markdown

登录后评论

基本信息

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

报告问题

第一次接触 MCP？

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

阅读入门指南

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