PluginBench
MCP Server
Active
Apache-2.0

io.github.VictoriaMetrics-Community/mcp-victoriatraces MCP Server

io.github.VictoriaMetrics-Community/mcp-victoriatraces

MCP server for VictoriaTraces—query traces, explore services, and access observability data with embedded documentation.

RepositoryRegistry
How to choose

What this kind of tool is for

  • Query, inspect, or seed a database without writing a one-off script.
  • Let your agent look up schema details before it writes migration code.
  • Move a small dataset between tools without leaving the terminal.

How to compare servers like this

Engine match:
Confirm it speaks your exact database and version, not just the family.
Access scope:
Read-only connections are the safe default — start there before granting writes.
Safety rails:
Check whether destructive statements need an explicit confirmation before they run.
Maintenance signal:
Database drivers change; a recently updated tool is less likely to break mid-query.

This page carries your copy-paste config: pick your MCP client in the install section on this page and use the copy button.

What is the io.github.VictoriaMetrics-Community/mcp-victoriatraces MCP server?

The VictoriaTraces MCP Server provides integration with VictoriaTraces APIs and documentation, enabling AI agents to query traces, list services, explore span operations, and analyze observability data. It includes embedded up-to-date VictoriaTraces documentation and supports read-only API operations for comprehensive trace analysis and debugging tasks.

This MCP server connects your VictoriaTraces instance to Claude, Cursor, and other AI clients, exposing tools for querying traces, discovering services and operations, analyzing dependencies, and searching documentation. Use it to automate trace exploration, debug distributed systems, and answer observability questions with AI assistance.

How to install io.github.VictoriaMetrics-Community/mcp-victoriatraces

Copy-paste configuration for popular MCP clients.

transport: stdio
Config generated by PluginBench — verify against the source before use.
Environment / auth
  • VT_INSTANCE_ENTRYPOINT
    required

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

  • VT_INSTANCE_BEARER_TOKEN
    required
    secret

    Authentication token for VictoriaMetrics API

  • MCP_DISABLED_TOOLS

    Comma-separated list of tools to disable

~/Library/Application Support/Claude/claude_desktop_config.json
JSON config
{
  "mcpServers": {
    "mcp-victoriatraces": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/victoriametrics-community/mcp-victoriatraces:1.5.0"
      ],
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE_ENTRYPOINT>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_INSTANCE_BEARER_TOKEN>",
        "MCP_DISABLED_TOOLS": "<YOUR_MCP_DISABLED_TOOLS>"
      }
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

  • documentation — Search in embedded VictoriaTraces documentation
  • services — List of all traced services
  • service_names — Get all the span names (operations) of a service
  • traces — Query traces
  • trace — Get trace info by trace ID
  • dependencies — Query the service dependency graph

Use cases

  • Query and analyze distributed traces to debug application performance issues
  • Discover all services and operations in your VictoriaTraces instance
  • Explore service dependencies and understand system architecture
  • Search VictoriaTraces documentation to answer configuration and usage questions
  • Automate trace investigation and root-cause analysis with AI assistance

io.github.VictoriaMetrics-Community/mcp-victoriatraces MCP server FAQ

What is the VictoriaTraces MCP Server?

It's an MCP server that integrates with VictoriaTraces, a distributed tracing backend. It provides tools to query traces, list services, explore operations, and access embedded documentation—all accessible to AI agents like Claude and Cursor.

Is it free?

Yes, the VictoriaTraces MCP Server is open-source and free to use. VictoriaTraces itself is also open-source.

How do I install it in Cursor or Claude Desktop?

Download the binary or build from source, then add it to your MCP configuration file (mcp.json for Cursor, claude_desktop_config.json for Claude Desktop) with your VictoriaTraces instance URL and optional bearer token.

What authentication is required?

You need the URL to your VictoriaTraces instance (VT_INSTANCE_ENTRYPOINT). Optionally, you can provide a bearer token (VT_INSTANCE_BEARER_TOKEN) and custom headers for authentication.

Does it support write operations?

No, the MCP server provides read-only access to VictoriaTraces APIs. It cannot create, modify, or delete traces.

What are the system requirements?

You need a running VictoriaTraces instance (single-node or cluster). For building from source, Go 1.25 or higher is required. Docker images are also available.

README (reference)

Source of truth, from the repository.

VictoriaTraces MCP Server

Latest Release Trust Score License Slack X Reddit

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

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:

    git clone https://github.com/VictoriaMetrics-Community/mcp-victoriatraces.git
    cd mcp-victoriatraces
    
  • Build binary from cloned source code:

    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:

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

Helm

Check out VictoriaTraces MCP Server Helm chart documentation for more details about installation using Helm.

Configuration

MCP Server for VictoriaTraces is configured via environment variables:

VariableDescriptionRequiredDefaultAllowed values
VT_INSTANCE_ENTRYPOINTURL to VictoriaTraces instanceYes--
VT_INSTANCE_BEARER_TOKENAuthentication token for VictoriaTraces APINo--
VT_INSTANCE_HEADERSCustom HTTP headers to send with requests (comma-separated key=value pairs)No--
VT_DEFAULT_TENANT_IDDefault tenant ID used when tenant is not specified in requests (format: AccountID:ProjectID or AccountID)No0:0-
MCP_SERVER_MODEServer operation mode. See Modes for details.Nostdiostdio, sse, http
MCP_LISTEN_ADDRAddress for SSE or HTTP server to listen onNolocalhost:8081-
MCP_DISABLED_TOOLSComma-separated list of tools to disableNo--
MCP_HEARTBEAT_INTERVALDefines the heartbeat interval for the streamable-http protocol. <br /> It means the MCP server will send a heartbeat to the client through the GET connection, <br /> to keep the connection alive from being closed by the network infrastructure (e.g. gateways)No30s-
MCP_LOG_FORMATLog output formatNotexttext, json
MCP_LOG_LEVELMinimum log levelNoinfodebug, info, warn, error

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:

С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:

EndpointDescription
/sse + /messageEndpoints for messages in SSE mode (for MCP clients that support SSE)
/mcpHTTP endpoint for streaming messages in HTTP mode (for MCP clients that support Streamable HTTP)
/metricsMetrics in Prometheus format for monitoring the MCP server
/health/livenessLiveness check endpoint to ensure the server is running
/health/readinessReadiness check endpoint to ensure the server is ready to accept requests

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:

{
  "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>"
      }
    }
  }
}

See Cursor MCP docs for more info.

Claude Desktop

Add this to your Claude Desktop claude_desktop_config.json file (you can find it if open 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>"
      }
    }
  }
}

See Claude Desktop MCP docs for more info.

Claude Code

Run the command:

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>"

See Claude Code MCP docs for more info.

Visual Studio Code

Add this to your VS Code MCP config file:

{
  "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>"
      }
    }
  }
}

See VS Code MCP docs for more info.

Zed

Add the following to your Zed config file:

  "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": {}
    }
  }
}

See Zed MCP docs for more info.

JetBrains IDEs

  • Open Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP).
  • Click Add (+)
  • Select As JSON
  • Put the following to the input field:
{
  "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

Add the following to your Windsurf MCP config file.

{
  "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>"
      }
    }
  }
}

See Windsurf MCP docs for more info.

Using Docker instead of binary

You can run VictoriaTraces MCP Server using Docker instead of local binary.

You should replace run command in configuration examples above in the following way:

{
  "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>"
      }
    }
  }
}

Usage

After installing and configuring the MCP server, you can start using it with your favorite MCP client.

You can start dialog with AI assistant from the phrase:

Use MCP VictoriaTraces in the following answers

But it's not required, you can just start asking questions and the assistant will automatically use the tools and documentation to provide you with the best answers.

Toolset

MCP VictoriaTraces provides numerous tools for interacting with your VictoriaTraces instance.

Here's a list of available tools:

ToolDescription
documentationSearch in embedded VictoriaTraces documentation
servicesList of all traced services
service_namesGet all the span names (operations) of a service
tracesQuery traces
traceGet trace info by trace ID
dependenciesQuery the service dependency graph

Prompts

The server includes pre-defined prompts for common tasks.

These are just examples at the moment, the prompt library will be added to in the future:

PromptDescription
documentationSearch VictoriaTraces documentation for specific topics

Roadmap

  • Implement multitenant version of MCP (that will support several deployments)
  • Add service graph tool after release of this feature (see the PR)

Disclaimer

AI services and agents along with MCP servers like this cannot guarantee the accuracy, completeness and reliability of results. You should double check the results obtained with AI.

The quality of the MCP Server and its responses depend very much on the capabilities of your client and the quality of the model you are using.

Contributing

Contributions to the MCP VictoriaTraces project are welcome!

Please feel free to submit issues, feature requests, or pull requests.

Related MCP servers

AI-powered anomaly detection integration for VictoriaMetrics with model management and alert generation

8
Go
Apache-2.0
View repository →

MCP server for VictoriaLogs—query logs, explore streams, and access observability APIs with AI agents.

86
Go
Apache-2.0
View repository →

MCP server for VictoriaMetrics providing API integration and read-only query capabilities for monitoring and observability.

184
Go
Apache-2.0
View repository →

MCP server for VictoriaLogs providing read-only API access, log querying, and embedded documentation search.

86
Go
Apache-2.0
View repository →

MCP server for VictoriaMetrics providing API access and embedded documentation for monitoring and observability tasks.

184
Go
Apache-2.0
View repository →

AI-powered anomaly detection integration for VictoriaMetrics via MCP

8
Go
Apache-2.0
View repository →