{
"markdown": "# VictoriaTraces MCP Server\n\n[](https://github.com/VictoriaMetrics-Community/mcp-victoriatraces/releases)\n[](https://archestra.ai/mcp-catalog/victoriametrics-community__mcp-victoriatraces)\n\n\n\n\n\nThe implementation of [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [VictoriaTraces](https://docs.victoriametrics.com/victoriatraces/).\n\nThis provides access to your VictoriaTraces instance and seamless integration with [VictoriaTraces APIs](https://docs.victoriametrics.com/victoriatraces/querying/#http-api) and [documentation](https://docs.victoriametrics.com/victoriatraces/).\nIt 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.\n\n## Features\n\nThis MCP server allows you to use almost all read-only APIs of VictoriaTraces:\n\n- Get services and operations (span names)\n- Query traces, explore and analyze traces data\n \nIn addition, the MCP server contains embedded up-to-date documentation and is able to search it without online access.\n\nMore details about the exact available tools and prompts can be found in the [Usage](#usage) section.\n\nYou can combine functionality of tools, docs search in your prompts and invent great usage scenarios for your VictoriaTraces instance.\nAnd 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.\n\nYou can also combine the MCP server with other observability or doc search MCP Servers and get even more powerful results.\n\n## Requirements\n\n- [VictoriaTraces](https://docs.victoriametrics.com/victoriatraces/) instance: ([single-node](https://docs.victoriametrics.com/victoriatraces/) or [cluster](https://docs.victoriametrics.com/victoriatraces/cluster/))\n- Go 1.25 or higher (if you want to build from source)\n\n## Installation\n\n### Go\n\n```bash\ngo install github.com/VictoriaMetrics-Community/mcp-victoriatraces/cmd/mcp-victoriatraces@latest\n```\n\n### Binaries\n\nJust download the latest release from [Releases](https://github.com/VictoriaMetrics-Community/mcp-victoriatraces/releases) page and put it to your PATH.\n\nExample for Linux x86_64 (note that other architectures and platforms are also available):\n\n```bash\nlatest=$(curl -s https://api.github.com/repos/VictoriaMetrics-Community/mcp-victoriatraces/releases/latest | grep 'tag_name' | cut -d\\\" -f4)\nwget https://github.com/VictoriaMetrics-Community/mcp-victoriatraces/releases/download/$latest/mcp-victoriatraces_Linux_x86_64.tar.gz\ntar axvf mcp-victoriatraces_Linux_x86_64.tar.gz\n```\n\n### Docker\n\nYou can run VictoriaTraces MCP Server using Docker.\n\nThis is the easiest way to get started without needing to install Go or build from source.\n\n```bash\ndocker run -d --name mcp-victoriatraces \\\n -e VT_INSTANCE_ENTRYPOINT=https://localhost:10428 \\\n -e MCP_SERVER_MODE=http \\\n -e MCP_LISTEN_ADDR=:8081 \\\n -p 8081:8081 \\\n ghcr.io/victoriametrics-community/mcp-victoriatraces\n```\n\nYou should replace environment variables with your own parameters.\n\nNote that the `MCP_SERVER_MODE=http` flag is used to enable Streamable HTTP mode. \nMore details about server modes can be found in the [Configuration](#configuration) section.\n\nSee available docker images in [github registry](https://github.com/orgs/VictoriaMetrics-Community/packages/container/package/mcp-victoriatraces).\n\nAlso see [Using Docker instead of binary](#using-docker-instead-of-binary) section for more details about using Docker with MCP server with clients in stdio mode.\n\n\n### Source Code\n\nFor building binary from source code you can use the following approach:\n\n- Clone repo:\n\n ```bash\n git clone https://github.com/VictoriaMetrics-Community/mcp-victoriatraces.git\n cd mcp-victoriatraces\n ```\n- Build binary from cloned source code:\n\n ```bash\n make build\n # after that you can find binary mcp-victoriatraces and copy this file to your PATH or run inplace\n ```\n- Build image from cloned source code:\n\n ```bash\n docker build -t mcp-victoriatraces .\n # after that you can use docker image mcp-victoriatraces for running or pushing\n ```\n\n## Configuration\n\nMCP Server for VictoriaTraces is configured via environment variables:\n\n| Variable | Description | Required | Default | Allowed values |\n|----------------------------|---------------------------------------------------------|----|--------|------------------------|\n| `VT_INSTANCE_ENTRYPOINT` | URL to VictoriaTraces instance | Yes | - | - |\n| `VT_INSTANCE_BEARER_TOKEN` | Authentication token for VictoriaTraces API | No | - | - |\n| `VT_INSTANCE_HEADERS` | Custom HTTP headers to send with requests (comma-separated key=value pairs) | No | - | - |\n| `VT_DEFAULT_TENANT_ID` | Default tenant ID used when tenant is not specified in requests (format: `AccountID:ProjectID` or `AccountID`) | No | `0:0` | - |\n| `MCP_SERVER_MODE` | Server operation mode. See [Modes](#modes) for details. | No | `stdio` | `stdio`, `sse`, `http` |\n| `MCP_LISTEN_ADDR` | Address for SSE or HTTP server to listen on | No | `localhost:8081` | - |\n| `MCP_DISABLED_TOOLS` | Comma-separated list of tools to disable | No | - | - |\n| `MCP_HEARTBEAT_INTERVAL` | Defines the heartbeat interval for the streamable-http protocol.
It means the MCP server will send a heartbeat to the client through the GET connection,
to keep the connection alive from being closed by the network infrastructure (e.g. gateways) | No | `30s` | - |\n| `MCP_LOG_FORMAT` | Log output format | No | `text` | `text`, `json` |\n| `MCP_LOG_LEVEL` | Minimum log level | No | `info` | `debug`, `info`, `warn`, `error` |\n\n### Modes\n\nMCP Server supports the following modes of operation (transports):\n\n- `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.\n- `sse` - Server-Sent Events. Server will expose the `/sse` and `/message` endpoints for SSE connections.\n- `http` - Streamable HTTP. Server will expose the `/mcp` endpoint for HTTP connections.\n\nMore info about traqnsports you can find in MCP docs:\n\n- [Core concepts -> Transports](https://modelcontextprotocol.io/docs/concepts/transports)\n- [Specifications -> Transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports)\n\n### Сonfiguration examples\n\n```bash\nexport VT_INSTANCE_ENTRYPOINT=\"https://localhost:10428\"\n\n# Custom headers for authentication (e.g., behind a reverse proxy)\n# Expected syntax is key=value separated by commas\nexport VT_INSTANCE_HEADERS=\"=,=\"\n\n# Server mode\nexport MCP_SERVER_MODE=\"sse\"\nexport MCP_SSE_ADDR=\"0.0.0.0:8082\"\n```\n\n## Endpoints\n\nIn SSE and HTTP modes the MCP server provides the following endpoints:\n\n| Endpoint | Description |\n|---------------------|--------------------------------------------------------------------------------------------------|\n| `/sse` + `/message` | Endpoints for messages in SSE mode (for MCP clients that support SSE) |\n| `/mcp` | HTTP endpoint for streaming messages in HTTP mode (for MCP clients that support Streamable HTTP) |\n| `/metrics` | Metrics in Prometheus format for monitoring the MCP server |\n| `/health/liveness` | Liveness check endpoint to ensure the server is running |\n| `/health/readiness` | Readiness check endpoint to ensure the server is ready to accept requests |\n\n## Setup in clients\n\n### Cursor\n\nGo to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` and paste the following configuration into your Cursor `~/.cursor/mcp.json` file:\n\n```json\n{\n \"mcpServers\": {\n \"victoriatraces\": {\n \"command\": \"/path/to/mcp-victoriatraces\",\n \"env\": {\n \"VT_INSTANCE_ENTRYPOINT\": \"\",\n \"VT_INSTANCE_BEARER_TOKEN\": \"\",\n \"VT_INSTANCE_HEADERS\": \"=,=\"\n }\n }\n }\n}\n```\n\nSee [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.\n\n### Claude Desktop\n\nAdd this to your Claude Desktop `claude_desktop_config.json` file (you can find it if open `Settings` -> `Developer` -> `Edit config`):\n\n```json\n{\n \"mcpServers\": {\n \"victoriatraces\": {\n \"command\": \"/path/to/mcp-victoriatraces\",\n \"env\": {\n \"VT_INSTANCE_ENTRYPOINT\": \"\",\n \"VT_INSTANCE_BEARER_TOKEN\": \"\",\n \"VT_INSTANCE_HEADERS\": \"=,=\"\n }\n }\n }\n}\n```\n\nSee [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info.\n\n### Claude Code\n\nRun the command:\n\n```sh\nclaude mcp add victoriatraces -- /path/to/mcp-victoriatraces \\\n -e VT_INSTANCE_ENTRYPOINT= \\\n -e VT_INSTANCE_BEARER_TOKEN= \\\n -e VT_INSTANCE_HEADERS=\"=,=\"\n```\n\nSee [Claude Code MCP docs](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp) for more info.\n\n### Visual Studio Code\n\nAdd this to your VS Code MCP config file:\n\n```json\n{\n \"servers\": {\n \"victoriatraces\": {\n \"type\": \"stdio\",\n \"command\": \"/path/to/mcp-victoriatraces\",\n \"env\": {\n \"VT_INSTANCE_ENTRYPOINT\": \"\",\n \"VT_INSTANCE_BEARER_TOKEN\": \"\",\n \"VT_INSTANCE_HEADERS\": \"=,=\"\n }\n }\n }\n}\n```\n\nSee [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.\n\n### Zed\n\nAdd the following to your Zed config file:\n\n```json\n \"context_servers\": {\n \"victoriatraces\": {\n \"command\": {\n \"path\": \"/path/to/mcp-victoriatraces\",\n \"args\": [],\n \"env\": {\n \"VT_INSTANCE_ENTRYPOINT\": \"\",\n \"VT_INSTANCE_BEARER_TOKEN\": \"\",\n \"VT_INSTANCE_HEADERS\": \"=,=\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\nSee [Zed MCP docs](https://zed.dev/docs/ai/mcp) for more info.\n\n### JetBrains IDEs\n\n- Open `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)`.\n- Click `Add (+)`\n- Select `As JSON`\n- Put the following to the input field:\n\n```json\n{\n \"mcpServers\": {\n \"victoriatraces\": {\n \"command\": \"/path/to/mcp-victoriatraces\",\n \"env\": {\n \"VT_INSTANCE_ENTRYPOINT\": \"\",\n \"VT_INSTANCE_BEARER_TOKEN\": \"\",\n \"VT_INSTANCE_HEADERS\": \"=,=\"\n }\n }\n }\n}\n```\n\n### Windsurf\n\nAdd the following to your Windsurf MCP config file.\n\n```json\n{\n \"mcpServers\": {\n \"victoriatraces\": {\n \"command\": \"/path/to/mcp-victoriatraces\",\n \"env\": {\n \"VT_INSTANCE_ENTRYPOINT\": \"\",\n \"VT_INSTANCE_BEARER_TOKEN\": \"\",\n \"VT_INSTANCE_HEADERS\": \"=,=\"\n }\n }\n }\n}\n```\n\nSee [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) for more info.\n\n### Using Docker instead of binary\n\nYou can run VictoriaTraces MCP Server using Docker instead of local binary.\n\nYou should replace run command in configuration examples above in the following way:\n\n```\n{\n \"mcpServers\": {\n \"victoriatraces\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\", \"--rm\",\n \"-e\", \"VT_INSTANCE_ENTRYPOINT\",\n \"-e\", \"VT_INSTANCE_BEARER_TOKEN\",\n \"-e\", \"VT_INSTANCE_HEADERS\",\n \"ghcr.io/victoriametrics-community/mcp-victoriatraces\",\n ],\n \"env\": {\n \"VT_INSTANCE_ENTRYPOINT\": \"\",\n \"VT_INSTANCE_BEARER_TOKEN\": \"\",\n \"VT_INSTANCE_HEADERS\": \"=,=\"\n }\n }\n }\n}\n```\n\n## Usage\n\nAfter [installing](#installation) and [configuring](#setup-in-clients) the MCP server, you can start using it with your favorite MCP client.\n\nYou can start dialog with AI assistant from the phrase:\n\n```\nUse MCP VictoriaTraces in the following answers\n```\n\nBut 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.\n\n### Toolset\n\nMCP VictoriaTraces provides numerous tools for interacting with your VictoriaTraces instance.\n\nHere's a list of available tools:\n\n| Tool | Description |\n|-----------------|--------------------------------------------------|\n| `documentation` | Search in embedded VictoriaTraces documentation |\n| `services` | List of all traced services |\n| `service_names` | Get all the span names (operations) of a service |\n| `traces` | Query traces |\n| `trace` | Get trace info by trace ID |\n| `dependencies` | Query the service dependency graph |\n\n### Prompts\n\nThe server includes pre-defined prompts for common tasks.\n\nThese are just examples at the moment, the prompt library will be added to in the future:\n\n| Prompt | Description |\n|-----------------|---------------------------------------------------------|\n| `documentation` | Search VictoriaTraces documentation for specific topics |\n\n## Roadmap\n \n- [ ] Implement multitenant version of MCP (that will support several deployments)\n- [x] Add service graph tool after release of [this feature](https://github.com/VictoriaMetrics/VictoriaTraces/pull/52) (see [the PR](#7))\n\n## Disclaimer\n\nAI services and agents along with MCP servers like this cannot guarantee the accuracy, completeness and reliability of results.\nYou should double check the results obtained with AI.\n\nThe 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.\n\n## Contributing\n\nContributions to the MCP VictoriaTraces project are welcome! \n\nPlease feel free to submit issues, feature requests, or pull requests.\n",
"bytes": 16473,
"sha": "ec247dfab5ea3a98a79098a4fa069d1a35b2807199200e438820ee1330b76089",
"repo_slug": "victoriametrics-community/mcp-victoriatraces",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_victoriametrics_community_mcp__324ab689/readme"
}