mcp-victoriametrics — Claude Code MCP server: how to install
Connects Claude Code to VictoriaMetrics instances for reading metrics, diagnosing alert rules, and querying embedded documentation.
claude mcp add --env VM_INSTANCE_ENTRYPOINT=<VM_INSTANCE_ENTRYPOINT> --env VM_INSTANCE_TYPE=<VM_INSTANCE_TYPE> --env VM_INSTANCE_BEARER_TOKEN=<VM_INSTANCE_BEARER_TOKEN> --env VMC_API_KEY=<VMC_API_KEY> --env MCP_DISABLED_TOOLS=<MCP_DISABLED_TOOLS> --transport stdio victoriametrics-mcp-victoriametrics -- docker run -i --rm -e VM_INSTANCE_ENTRYPOINT -e VM_INSTANCE_TYPE -e VM_INSTANCE_BEARER_TOKEN -e VMC_API_KEY -e MCP_DISABLED_TOOLS ghcr.io/victoriametrics/mcp-victoriametrics:1.120.1What mcp-victoriametrics does
This MCP server exposes read-only endpoints from VictoriaMetrics to your coding assistant. The model can inspect time series, review label values, check cardinality hotspots, and explain query execution plans. It also tests alerting rules and relabeling configs directly inside your chat session.
The server bundles a complete copy of the official documentation, enabling offline searches when formulating queries. You need either a self-hosted single-node or cluster instance, or VictoriaMetrics Cloud credentials. Without a reachable VM_INSTANCE_ENTRYPOINT, tools cannot pull telemetry. If you just want to experiment, point your client at the public playground at https://play-mcp.victoriametrics.com/mcp.
What it helps with
- Run read-only metric queries and inspect time series
- Evaluate label cardinality and monitor metric usage
- Verify alerting rules and debug relabeling policies
- Search VictoriaMetrics documentation without internet access
Example prompts for the agent
- Check the highest cardinality labels in our VictoriaMetrics cluster
- Explain why this alerting rule failed and suggest query fixes
- Search embedded docs for downsampling retention parameters
How to install mcp-victoriametrics
Platform CLI
claude mcp add --env VM_INSTANCE_ENTRYPOINT=<VM_INSTANCE_ENTRYPOINT> --env VM_INSTANCE_TYPE=<VM_INSTANCE_TYPE> --env VM_INSTANCE_BEARER_TOKEN=<VM_INSTANCE_BEARER_TOKEN> --env VMC_API_KEY=<VMC_API_KEY> --env MCP_DISABLED_TOOLS=<MCP_DISABLED_TOOLS> --transport stdio victoriametrics-mcp-victoriametrics -- docker run -i --rm -e VM_INSTANCE_ENTRYPOINT -e VM_INSTANCE_TYPE -e VM_INSTANCE_BEARER_TOKEN -e VMC_API_KEY -e MCP_DISABLED_TOOLS ghcr.io/victoriametrics/mcp-victoriametrics:1.120.1Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
codex mcp add victoriametrics-mcp-victoriametrics --env VM_INSTANCE_ENTRYPOINT=<VM_INSTANCE_ENTRYPOINT> --env VM_INSTANCE_TYPE=<VM_INSTANCE_TYPE> --env VM_INSTANCE_BEARER_TOKEN=<VM_INSTANCE_BEARER_TOKEN> --env VMC_API_KEY=<VMC_API_KEY> --env MCP_DISABLED_TOOLS=<MCP_DISABLED_TOOLS> -- docker run -i --rm -e VM_INSTANCE_ENTRYPOINT -e VM_INSTANCE_TYPE -e VM_INSTANCE_BEARER_TOKEN -e VMC_API_KEY -e MCP_DISABLED_TOOLS ghcr.io/victoriametrics/mcp-victoriametrics:1.120.1Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"mcpServers": {
"victoriametrics-mcp-victoriametrics": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"VM_INSTANCE_ENTRYPOINT",
"-e",
"VM_INSTANCE_TYPE",
"-e",
"VM_INSTANCE_BEARER_TOKEN",
"-e",
"VMC_API_KEY",
"-e",
"MCP_DISABLED_TOOLS",
"ghcr.io/victoriametrics/mcp-victoriametrics:1.120.1"
],
"env": {
"VM_INSTANCE_ENTRYPOINT": "<VM_INSTANCE_ENTRYPOINT>",
"VM_INSTANCE_TYPE": "<VM_INSTANCE_TYPE>",
"VM_INSTANCE_BEARER_TOKEN": "<VM_INSTANCE_BEARER_TOKEN>",
"VMC_API_KEY": "<VMC_API_KEY>",
"MCP_DISABLED_TOOLS": "<MCP_DISABLED_TOOLS>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"servers": {
"victoriametrics-mcp-victoriametrics": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"VM_INSTANCE_ENTRYPOINT",
"-e",
"VM_INSTANCE_TYPE",
"-e",
"VM_INSTANCE_BEARER_TOKEN",
"-e",
"VMC_API_KEY",
"-e",
"MCP_DISABLED_TOOLS",
"ghcr.io/victoriametrics/mcp-victoriametrics:1.120.1"
],
"env": {
"VM_INSTANCE_ENTRYPOINT": "<VM_INSTANCE_ENTRYPOINT>",
"VM_INSTANCE_TYPE": "<VM_INSTANCE_TYPE>",
"VM_INSTANCE_BEARER_TOKEN": "<VM_INSTANCE_BEARER_TOKEN>",
"VMC_API_KEY": "<VMC_API_KEY>",
"MCP_DISABLED_TOOLS": "<MCP_DISABLED_TOOLS>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
gemini mcp add -e VM_INSTANCE_ENTRYPOINT=<VM_INSTANCE_ENTRYPOINT> -e VM_INSTANCE_TYPE=<VM_INSTANCE_TYPE> -e VM_INSTANCE_BEARER_TOKEN=<VM_INSTANCE_BEARER_TOKEN> -e VMC_API_KEY=<VMC_API_KEY> -e MCP_DISABLED_TOOLS=<MCP_DISABLED_TOOLS> victoriametrics-mcp-victoriametrics docker run -i --rm -e VM_INSTANCE_ENTRYPOINT -e VM_INSTANCE_TYPE -e VM_INSTANCE_BEARER_TOKEN -e VMC_API_KEY -e MCP_DISABLED_TOOLS ghcr.io/victoriametrics/mcp-victoriametrics:1.120.1Replace <…> with your own values. 2 more environment variables are in the server README
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-victoriametrics
How do I install mcp-victoriametrics in Claude Code?
Add the Docker container by running `claude mcp add --env VM_INSTANCE_ENTRYPOINT=<VM_INSTANCE_ENTRYPOINT> --env VM_INSTANCE_TYPE=<VM_INSTANCE_TYPE> --env VM_INSTANCE_BEARER_TOKEN=<VM_INSTANCE_BEARER_TOKEN> --env VMC_API_KEY=<VMC_API_KEY> --env MCP_DISABLED_TOOLS=<MCP_DISABLED_TOOLS> --transport stdio victoriametrics-mcp-victoriametrics -- docker run -i --rm -e VM_INSTANCE_ENTRYPOINT -e VM_INSTANCE_TYPE -e VM_INSTANCE_BEARER_TOKEN -e VMC_API_KEY -e MCP_DISABLED_TOOLS ghcr.io/victoriametrics/mcp-victoriametrics:1.120.1`. Replace the placeholders with your endpoint details.
What does mcp-victoriametrics do?
It interfaces assistants with VictoriaMetrics to inspect time series, evaluate recording rules, and audit metric usage. It also provides offline access to product documentation.
Can I evaluate mcp-victoriametrics without deploying VictoriaMetrics?
Yes, you can connect your client to the public endpoint https://play-mcp.victoriametrics.com/mcp. It runs in Streamable HTTP mode against the public playground.
