mcp-victoriatraces — Claude Code MCP server for traces
Connect an AI client to VictoriaTraces to find services and operations, query traces, and search the bundled docs. Useful when investigating trace data or debugging.
claude mcp add --env VT_INSTANCE_ENTRYPOINT=<VT_INSTANCE_ENTRYPOINT> --env VT_INSTANCE_BEARER_TOKEN=<VT_INSTANCE_BEARER_TOKEN> --env MCP_DISABLED_TOOLS=<MCP_DISABLED_TOOLS> --transport stdio mcp-victoriatraces -- 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.0What mcp-victoriatraces does
The server connects to a VictoriaTraces instance and exposes read-only tools for finding services and operations, then querying and examining traces. VictoriaTraces documentation is bundled with the server and can be searched offline.
A VictoriaTraces instance is required. Set its address with VT_INSTANCE_ENTRYPOINT; an API token can be supplied through VT_INSTANCE_BEARER_TOKEN. The Claude Code setup uses Docker. Responses depend on the client and model, which matters when using the results to investigate traces.
What it helps with
- find services in a VictoriaTraces instance
- list operations and span names
- query and inspect trace data
- search VictoriaTraces docs without network access
Example prompts for the agent
- Find the services and operations in my VictoriaTraces instance.
- Query traces for this service and help me inspect the results.
- Search the VictoriaTraces docs for how to query traces.
How to install mcp-victoriatraces
Platform CLI
claude mcp add --env VT_INSTANCE_ENTRYPOINT=<VT_INSTANCE_ENTRYPOINT> --env VT_INSTANCE_BEARER_TOKEN=<VT_INSTANCE_BEARER_TOKEN> --env MCP_DISABLED_TOOLS=<MCP_DISABLED_TOOLS> --transport stdio mcp-victoriatraces -- 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.0Replace <…> with your own values
Platform CLI
codex mcp add mcp-victoriatraces --env VT_INSTANCE_ENTRYPOINT=<VT_INSTANCE_ENTRYPOINT> --env VT_INSTANCE_BEARER_TOKEN=<VT_INSTANCE_BEARER_TOKEN> --env 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.0Replace <…> with your own values
Config file
{
"mcpServers": {
"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>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp-victoriatraces": {
"type": "stdio",
"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>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e VT_INSTANCE_ENTRYPOINT=<VT_INSTANCE_ENTRYPOINT> -e VT_INSTANCE_BEARER_TOKEN=<VT_INSTANCE_BEARER_TOKEN> -e MCP_DISABLED_TOOLS=<MCP_DISABLED_TOOLS> mcp-victoriatraces 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.0Replace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-victoriatraces
How do I install mcp-victoriatraces in Claude Code?
Run: `claude mcp add --env VT_INSTANCE_ENTRYPOINT=<VT_INSTANCE_ENTRYPOINT> --env VT_INSTANCE_BEARER_TOKEN=<VT_INSTANCE_BEARER_TOKEN> --env MCP_DISABLED_TOOLS=<MCP_DISABLED_TOOLS> --transport stdio mcp-victoriatraces -- 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. Set VT_INSTANCE_ENTRYPOINT` to your VictoriaTraces instance address.
What does mcp-victoriatraces do?
It connects an AI client to VictoriaTraces and provides tools to find services and operations, query traces, and inspect trace data. It also includes searchable documentation that works offline.
Does mcp-victoriatraces require an API token?
You need a VictoriaTraces instance address in VT_INSTANCE_ENTRYPOINT. The API token setting, VT_INSTANCE_BEARER_TOKEN, is optional.
