项目简介

VictoriaTraces MCP 服务器是基于 Model Context Protocol (MCP) 实现的后端应用，旨在将您的 VictoriaTraces 实例无缝集成到各种支持 MCP 的 LLM 客户端中。它通过标准化的方式，允许 LLM 客户端访问 VictoriaTraces 的 API 接口，查询追踪数据、服务信息以及进行文档搜索，从而增强 LLM 在可观测性、调试和自动化任务中的能力。

主要功能点

追踪数据查询: 允许 LLM 查询、探索和分析 VictoriaTraces 中的追踪数据。
服务及操作列表: 获取 VictoriaTraces 中所有被追踪的服务及其 Span 名称（操作）。
服务依赖图: 查询服务之间的依赖关系图。
离线文档搜索: 内嵌 VictoriaTraces 的最新文档，支持 LLM 客户端无需在线访问即可搜索文档。
LLM 工具集成: 将 VictoriaTraces 的读写 API 封装成可供 LLM 调用的“工具”，实现 LLM 与追踪系统的深度交互。
可定制的 Prompt 模板: 支持定义和渲染 Prompt 模板，以适应不同的 LLM 交互模式。

安装步骤

您可以选择通过 Go 工具、下载预编译二进制文件、使用 Docker 或从源代码构建来安装 VictoriaTraces MCP 服务器。

通过 Go 安装: 如果您已安装 Go 1.25 或更高版本，可运行以下命令：

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

下载二进制文件: 直接从 GitHub Releases 页面下载最新版本的预编译二进制包，解压后将其可执行文件（例如 'mcp-victoriatraces_Linux_x86_64'）添加到您的系统 PATH 中。

使用 Docker 运行: 推荐使用 Docker 快速部署，无需安装 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

请将 'VT_INSTANCE_ENTRYPOINT' 替换为您的 VictoriaTraces 实例地址。

从源代码构建: 克隆仓库后，进入项目目录执行 'make build'。

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令及其环境变量才能建立连接。以下是常见 MCP 客户端的配置示例。您需要将 '<YOUR_VT_INSTANCE>' 替换为您的 VictoriaTraces 实例 URL，并可选提供 '<YOUR_VT_BEARER_TOKEN>' 和自定义 HTTP 头部。

对于 Cursor, Claude Desktop, JetBrains IDEs, Windsurf 客户端: 在您的客户端 MCP 配置文件中添加如下 JSON 片段：

{
  "mcpServers": {
    "victoriatraces": {
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<您的VictoriaTraces实例URL，例如 https://localhost:10428>",
        "VT_INSTANCE_BEARER_TOKEN": "<可选：您的VictoriaTraces API认证Bearer Token>",
        "VT_INSTANCE_HEADERS": "<可选：自定义HTTP头部，例如 \"X-Auth-Key=your_key,X-Request-ID=123\"，键值对用逗号分隔>"
      }
    }
  }
}

对于 Claude Code 客户端 (命令行): 运行以下命令：

claude mcp add victoriatraces -- /path/to/mcp-victoriatraces \
  -e VT_INSTANCE_ENTRYPOINT=<您的VictoriaTraces实例URL> \
  -e VT_INSTANCE_BEARER_TOKEN=<可选：您的VictoriaTraces API认证Bearer Token> \
  -e VT_INSTANCE_HEADERS="<可选：自定义HTTP头部，键值对用逗号分隔>"

对于 Visual Studio Code 客户端: 在您的 VS Code MCP 配置文件中添加如下 JSON 片段：

{
  "servers": {
    "victoriatraces": {
      "type": "stdio",
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<您的VictoriaTraces实例URL>",
        "VT_INSTANCE_BEARER_TOKEN": "<可选：您的VictoriaTraces API认证Bearer Token>",
        "VT_INSTANCE_HEADERS": "<可选：自定义HTTP头部，键值对用逗号分隔>"
      }
    }
  }
}

对于 Zed 客户端: 在您的 Zed 配置文件中添加如下 JSON 片段：

  "context_servers": {
    "victoriatraces": {
      "command": {
        "path": "/path/to/mcp-victoriatraces",
        "args": [],
        "env": {
          "VT_INSTANCE_ENTRYPOINT": "<您的VictoriaTraces实例URL>",
          "VT_INSTANCE_BEARER_TOKEN": "<可选：您的VictoriaTraces API认证Bearer Token>",
          "VT_INSTANCE_HEADERS": "<可选：自定义HTTP头部，键值对用逗号分隔>"
        }
      },
      "settings": {}
    }
  }

使用 Docker 代替本地二进制的配置方式 (适用于所有客户端): 您可以将 'command' 设置为 'docker'，并在 'args' 中传入 'docker run' 命令所需的参数，如下所示：

{
  "mcpServers": {
    "victoriatraces": {
      "command": "docker",
        "args": [
          "run",
          "-i", "--rm",
          "-e", "VT_INSTANCE_ENTRYPOINT=<您的VictoriaTraces实例URL>",
          "-e", "VT_INSTANCE_BEARER_TOKEN=<可选：您的VictoriaTraces API认证Bearer Token>",
          "-e", "VT_INSTANCE_HEADERS=<可选：自定义HTTP头部，键值对用逗号分隔>",
          "ghcr.io/victoriametrics-community/mcp-victoriatraces"
        ],
      "env": {}
    }
  }
}

基本使用方法

配置完成后，您可以在支持 MCP 的 LLM 客户端中直接与 VictoriaTraces MCP 服务器交互。您可以通过以下方式启动对话，让 AI 助手知道要使用 VictoriaTraces：

Use MCP VictoriaTraces in the following answers

或者，AI 助手也可能根据您的问题自动识别并调用 VictoriaTraces 的功能。您可以直接向 AI 提问，例如：

“列出所有追踪到的服务。” (对应 'services' 工具)
“查询服务 'my-app' 的所有操作名称。” (对应 'service_names' 工具)
“查找所有包含错误的服务追踪。” (对应 'traces' 工具)
“根据追踪 ID 'abc-123' 获取详细追踪信息。” (对应 'trace' 工具)
“搜索 VictoriaTraces 文档中关于 'span attributes' 的内容。” (对应 'documentation' 工具)

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息