VictoriaMetrics MCP Server

Add to your client

Copy the config for your MCP client and paste it into its config file.

{
  "mcpServers": {
    "victoriametrics-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VM_INSTANCE_ENTRYPOINT",
        "-e",
        "VM_INSTANCE_TYPE",
        "-e",
        "VM_INSTANCE_BEARER_TOKEN",
        "ghcr.io/victoriametrics/mcp-victoriametrics"
      ],
      "env": {
        "VM_INSTANCE_TYPE": "single",
        "VM_INSTANCE_ENTRYPOINT": "<your-victoriametrics-url>",
        "VM_INSTANCE_BEARER_TOKEN": "<your-bearer-token>"
      }
    }
  }
}

Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf

Before you start

• A VictoriaMetrics instance (single-node or cluster) or a VictoriaMetrics Cloud account
• The instance URL set as VM_INSTANCE_ENTRYPOINT, plus VM_INSTANCE_TYPE set to 'single' or 'cluster'
• Optional auth: a bearer token via VM_INSTANCE_BEARER_TOKEN, custom headers via VM_INSTANCE_HEADERS (for reverse proxies), or a VictoriaMetrics Cloud API key via VMC_API_KEY
• To run: download a release binary, use the Docker image (ghcr.io/victoriametrics/mcp-victoriametrics), or build from source with Go 1.26+

About VictoriaMetrics MCP Server

Tools & capabilities (12)

When to use it

• Use it when you want to write and run MetricsQL/PromQL queries conversationally and have the agent prettify or explain them.
• Use it when you're hunting high-cardinality metrics and want tsdb_status and metric statistics to find the culprits.
• Use it when validating alerting rules or checking which alerts are currently firing.
• Use it when debugging relabeling, downsampling, or retention filter configuration before applying it.
• Use it when you need a VictoriaMetrics config or query-syntax answer and want the agent to search the embedded docs.
• Use it when managing VictoriaMetrics Cloud deployments, regions, and access tokens through an agent.

Quick setup

1. 1Have your VictoriaMetrics URL (or VictoriaMetrics Cloud account) ready.
2. 2Install the server via the release binary, the ghcr.io Docker image, or `make build` from source (Go 1.26+).
3. 3Add it to your MCP client config and set VM_INSTANCE_ENTRYPOINT and VM_INSTANCE_TYPE (single/cluster); add VM_INSTANCE_BEARER_TOKEN or VMC_API_KEY if auth is required.
4. 4Optionally set MCP_SERVER_MODE (stdio/sse/http) and MCP_DISABLED_TOOLS to trim the toolset.
5. 5Restart your MCP client.
6. 6Verify by asking the agent to list metrics or run a simple range query.

VictoriaMetrics MCP Server FAQ