Summary

Read-only by construction, and it brings its own documentation.

The scope is drawn at what VMUI can do, which means an assistant can investigate a cardinality blow-up or a slow query without any way to change the instance. Bundling searchable VictoriaMetrics documentation into the binary is the part that pays off in practice: the model stops guessing at MetricsQL syntax and flag names because it can look them up, offline, in the same session.

What it is

The MCP server for VictoriaMetrics, covering essentially all of the read-only API surface — the same functions available in VMUI — plus embedded, up-to-date VictoriaMetrics documentation it can search offline. It works against a single-node instance, a cluster, or VictoriaMetrics Cloud.

What you get

Instant and range PromQL/MetricsQL queries, with clients that support it able to draw the result — `query`, `query_range`
Data exploration across metric names, metadata, label names, label values and series — `metrics`, `metrics_metadata`, `labels`, `label_values`, `series`
Alerting and recording rules plus current firing and pending alerts — `rules`, `alerts`
Cardinality and usage analysis: which metrics are expensive, which are never queried, what the TSDB status looks like — `tsdb_status`, `metric_statistics`, `top_queries`, `active_queries`
Query authoring help — reformatting a query, and parsing one to explain how it works — `prettify_query`, `explain_query`
Embedded documentation search that needs no online access — `documentation`
Multi-tenant support with `tenants` and a `VM_DEFAULT_TENANT_ID` in `accountID:projectID` form
VictoriaMetrics Cloud tools for deployments, providers, regions, tiers, access tokens and rule files — `deployments`, `access_tokens`, `rule_filenames`, `rule_file`
Three ready-made prompts, including one that finds never-queried metrics and writes relabel configs to stop ingesting them — `unused_metrics`, `rarely_used_metrics_with_high_cardinality`

Requirements

A VictoriaMetrics instance — single-node or cluster — or a VictoriaMetrics Cloud deployment. Set `VM_INSTANCE_ENTRYPOINT` to the root URL of vmsingle or vmselect and `VM_INSTANCE_TYPE` to `single` or `cluster`; with Cloud you use `VMC_API_KEY` instead. `VM_INSTANCE_BEARER_TOKEN`, `VM_INSTANCE_HEADERS` and `MCP_PASSTHROUGH_HEADERS` cover authentication behind a proxy. `MCP_SERVER_MODE` chooses `stdio`, `sse` or `http`, and HTTP mode listens on `MCP_LISTEN_ADDR`, default `localhost:8080`. Install a release binary, the Docker image, or a Helm chart; building from source needs Go 1.26 or higher. Six tools ship disabled by default — `export`, `flags`, `metric_relabel_debug`, `downsampling_filters_debug`, `retention_filters_debug` and `test_rules` — and are enabled by editing `MCP_DISABLED_TOOLS`. A public instance at `https://play-mcp.victoriametrics.com/mcp` runs against the VictoriaMetrics playground if you want to try it before installing.

Setup effort

One command — docker run -d --name mcp-victoriametrics -e VM_INSTANCE_ENTRYPOINT=https://play.victoriametrics.com -e VM_INSTANCE_TYPE=cluster -e MCP_SERVER_MODE=sse -e MCP_LISTEN_ADDR=:8080 -p 8080:8080 ghcr.io/victoriametrics/mcp-victoriametrics