How to add VictoriaMetrics MCP Server to Claude Desktop

Official VictoriaMetrics server: MetricsQL/PromQL queries plus embedded docs search. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 15, 2026 · 130★ · stdio · apikey · official

Claude Desktop config for VictoriaMetrics MCP Server

docker run -i --rm -e VM_INSTANCE_ENTRYPOINT -e VM_INSTANCE_TYPE -e VM_INSTANCE_BEARER_TOKEN ghcr.io/victoriametrics/mcp-victoriametrics

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

Requires Docker to be installed and running.

Setup steps

1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
2Paste the VictoriaMetrics MCP Server config below under the top-level "mcpServers" key.
3Fill in any placeholder secrets (API keys, paths) in the snippet.
4Save the file, then fully quit and reopen Claude Desktop.
5Open a chat and confirm VictoriaMetrics MCP Server's tools appear under the 🔌 tools menu.

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+

What VictoriaMetrics MCP Server can do in Claude Desktop

query

Run an instant PromQL/MetricsQL query.

query_range

Run a PromQL/MetricsQL query over a time range.

metrics

List available metric names in the instance.

labels

List label names; with label_values, explore label cardinality.

series

Find time series matching a selector.

explain_query

Analyze and explain a MetricsQL/PromQL query.

prettify_query

Format a query for readability.

documentation

Search the embedded VictoriaMetrics documentation.

Security

The bearer token grants query access to all stored time-series, so scope it and keep the instance endpoint network-restricted. MetricsQL queries can be heavy, so apply server-side limits on large unbounded ranges.

VictoriaMetrics MCP Server + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the VictoriaMetrics MCP Server config there under the "mcpServers" key and restart the client.

Is VictoriaMetrics MCP Server safe to use with Claude Desktop?

Is this an official VictoriaMetrics project?

Yes, it is maintained under the VictoriaMetrics-Community organization on GitHub and distributed via the project's own GitHub Container Registry and Helm chart.

Does it support both single-node and cluster setups?

Yes. Set VM_INSTANCE_TYPE to 'single' or 'cluster'. Cluster and multi-tenant deployments are supported, including a `tenants` tool.

How do I authenticate?

Use a bearer token via VM_INSTANCE_BEARER_TOKEN, custom headers via VM_INSTANCE_HEADERS for reverse-proxy auth, or a VMC_API_KEY for VictoriaMetrics Cloud.

View repo Full VictoriaMetrics MCP Server page