VictoriaTraces MCP Server

The implementation of Model Context Protocol (MCP) server for VictoriaTraces.

This provides access to your VictoriaTraces instance and seamless integration with VictoriaTraces APIs and documentation. It can give you a comprehensive interface for traces, observability, and debugging tasks related to your VictoriaTraces instances, enable advanced automation and interaction capabilities for engineers and tools.

Features

This MCP server allows you to use almost all read-only APIs of VictoriaTraces:

• Get services and operations (span names)
• Query traces, explore and analyze traces data

In addition, the MCP server contains embedded up-to-date documentation and is able to search it without online access.

More details about the exact available tools and prompts can be found in the Usage section.

You can combine functionality of tools, docs search in your prompts and invent great usage scenarios for your VictoriaTraces instance. And please note the fact that the quality of the MCP Server and its responses depends very much on the capabilities of your client and the quality of the model you are using.

You can also combine the MCP server with other observability or doc search MCP Servers and get even more powerful results.

Requirements

• VictoriaTraces instance: (single-node or cluster)
• Go 1.25 or higher (if you want to build from source)

Installation

Go

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

Binaries

Just download the latest release from Releases page and put it to your PATH.

Example for Linux x86_64 (note that other architectures and platforms are also available):

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

You can run VictoriaTraces MCP Server using Docker.

This is the easiest way to get started without needing to install Go or build from source.

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

You should replace environment variables with your own parameters.

Note that the MCP_SERVER_MODE=http flag is used to enable Streamable HTTP mode. More details about server modes can be found in the Configuration section.

See available docker images in github registry.

Also see Using Docker instead of binary section for more details about using Docker with MCP server with clients in stdio mode.

Source Code

For building binary from source code you can use the following approach:

• Clone repo:

  bash

  Copy

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

• Build binary from cloned source code:

  bash

  Copy

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

• Build image from cloned source code:

  Terminal

  Copy

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

Configuration

MCP Server for VictoriaTraces is configured via environment variables:

Modes

MCP Server supports the following modes of operation (transports):

• stdio - Standard input/output mode, where the server reads commands from standard input and writes responses to standard output. This is the default mode and is suitable for local servers.
• sse - Server-Sent Events. Server will expose the /sse and /message endpoints for SSE connections.
• http - Streamable HTTP. Server will expose the /mcp endpoint for HTTP connections.

More info about traqnsports you can find in MCP docs:

• Core concepts -> Transports
• Specifications -> Transports

Сonfiguration examples

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"

Endpoints

In SSE and HTTP modes the MCP server provides the following endpoints:

Setup in clients

Cursor

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server and paste the following configuration into your Cursor ~/.cursor/mcp.json file: