MCP Victoriametrics

What VictoriaMetrics-Community/mcp-victoriametrics does

VictoriaMetrics-Community/mcp-victoriametrics gives MCP clients an interface to a VictoriaMetrics single-node, cluster, or VictoriaMetrics Cloud instance. Its tools cover read-only API operations for exploring stored metrics, running PromQL or MetricsQL queries, inspecting alerting and recording rules, and investigating query performance or TSDB cardinality.

The server also includes an embedded VictoriaMetrics documentation resource. A documentation search tool returns relevant resource URIs, allowing an agent to retrieve product context without requiring online documentation access. Query analysis tools can explain or format MetricsQL expressions, while metadata and usage statistics help identify metric definitions and query activity.

How it works

The MCP process translates tool calls into requests to VictoriaMetrics APIs. Instant and range queries use the corresponding query endpoints; label, metric, metadata, series, alert, rule, tenant, and status tools map to their respective VictoriaMetrics or vmalert API endpoints. The server can inspect active queries, rank frequently or expensively executed queries, and report TSDB cardinality details such as high-cardinality metric names, labels, values, and label-name pairs.

Supported operation modes include stdio and HTTP-based serving. Streamable HTTP mode can expose a root endpoint with setup instructions and tool inspection. A public test instance is available at https://play-mcp.victoriametrics.com/mcp; it is intended for MCP clients and connects to the VictoriaMetrics Playground.

Setup and configuration

Run the server from a downloaded release binary, a Docker image, a Helm deployment, or a locally built binary. Source builds use Go 1.26 or newer and the repository's make build target. Docker images are published through the VictoriaMetrics GitHub Container Registry.

Configuration uses environment variables. Set VM_INSTANCE_ENTRYPOINT to the root URL of a VictoriaMetrics single-node instance or vmselect endpoint, or configure VMC_API_KEY for VictoriaMetrics Cloud access. VM_INSTANCE_TYPE identifies the instance type. HTTP deployments can set MCP_SERVER_MODE, MCP_LISTEN_ADDR, and MCP_AUTH_TOKEN; the documented Docker example uses port 8080 and Streamable HTTP or SSE mode.

A typical Docker deployment supplies the VictoriaMetrics endpoint, instance type, server mode, listen address, and authentication token, then publishes the selected listen port. Client configuration depends on whether the process is launched over stdio or reached through an HTTP MCP endpoint. Claude Desktop is shown as a supported client configuration.

The available operations are read-only. They are intended for querying, inspection, analysis, and documentation lookup rather than changing VictoriaMetrics data or configuration.