MCP Victoriametrics

What mcp-victoriametrics does

mcp-victoriametrics exposes VictoriaMetrics APIs through the Model Context Protocol. It is intended for read-only investigation of VictoriaMetrics and VictoriaMetrics Cloud deployments, including single-node and cluster configurations. The available tools cover metric querying, metadata and label exploration, alerting inspection, query analysis, and database usage statistics.

The server also includes searchable VictoriaMetrics documentation. Documentation results are returned as relevant resource URIs, giving an MCP client additional context for VictoriaMetrics questions without requiring an online documentation lookup.

How it works

The server connects to a configured VictoriaMetrics instance and translates MCP tool calls into VictoriaMetrics API requests. Instant queries use the /api/v1/query endpoint, while range queries use /api/v1/query_range with a start time, end time, and step. Query results contain matching time series and their values at the requested evaluation times.

Discovery tools use API endpoints for metric names, labels, label values, series, and metric metadata. Alert and recording-rule inspection is provided through the vmalert APIs proxied by VictoriaMetrics. Additional endpoints expose active queries, top-query statistics, metric usage statistics, and TSDB cardinality information.

Query-focused tools can explain MetricsQL, format a MetricsQL query, and help inspect how queries operate. The documentation search is backed by embedded resources, so it can work without online access to the VictoriaMetrics documentation site.

The server can run in standard input/output mode or over HTTP-based modes. Streamable HTTP mode also provides a root endpoint with setup instructions and tool inspection. A public test endpoint is available at https://play-mcp.victoriametrics.com/mcp; it is intended for MCP clients and is configured for the VictoriaMetrics Playground.

Setup and configuration

A VictoriaMetrics or VictoriaMetrics Cloud instance is required. Prebuilt binaries are available from the project's releases, and Docker images are published through the VictoriaMetrics GitHub Container Registry. The project also supports building from source with Go 1.26 or later and provides a Helm installation path.

Configure the connection with environment variables. VM_INSTANCE_ENTRYPOINT points to the root URL of a vmsingle or vmselect instance. VMC_API_KEY can be used instead for VictoriaMetrics Cloud access. VM_INSTANCE_TYPE identifies the VictoriaMetrics instance type when required by the selected connection. Docker deployments can set the server mode and listening address through environment variables; the documented examples use MCP_SERVER_MODE and MCP_LISTEN_ADDR.

Tools and capabilities

• Run instant PromQL or MetricsQL queries.
• Run range queries over a specified time interval and step.
• List metric names, labels, label values, and time series.
• Inspect metric metadata, including type, help text, and unit.
• Review firing and pending alerts, alerting rules, and recording rules.
• Examine active queries, top queries, metric usage, and TSDB cardinality.
• Explain and prettify MetricsQL queries.
• Search embedded VictoriaMetrics documentation.
• List tenants available through the VictoriaMetrics tenant endpoint.

Limitations and notes

The exposed API functionality is read-only. Results and responses depend on the permissions and data available through the configured VictoriaMetrics instance, as well as the MCP client and model handling the tool calls. The public playground endpoint is for MCP-client use rather than direct browser access. Features such as graph rendering depend on whether the connected client supports them.