How to add VictoriaMetrics MCP Server to Windsurf

Official VictoriaMetrics server: MetricsQL/PromQL queries plus embedded docs search. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf 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 Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the VictoriaMetrics MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5VictoriaMetrics MCP Server's tools become available to Cascade.

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 Windsurf

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 + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_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 Windsurf?

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