# mcp-victoriametrics [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/VictoriaMetrics/mcp-victoriametrics  
**GitHub Stars:** 247  
**Views:** 8  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-victoriametrics

## Description
MCP Server for VictoriaMetrics. Provides integration with VictoriaMetrics API and documentation

## Tools
Capabilities this server exposes over MCP:

- **active_queries** — Active queries. This tool can determine currently active queries in the VictoriaMetrics instance.
This information is obtained from the "/api/v1/status/active_queries" HTTP endpoint of VictoriaMetrics API.
- **alerts** — List of firing and pending alerts of the VictoriaMetrics instance. This tool uses `/api/v1/alerts` endpoint of vmalert API, proxied by VictoriaMetrics API.
- **documentation** — Search documentation resources for the given search query, returning the URIs of the resources that match the search criteria sorted by relevance. This tool can help to get context for any VictoriaMetrics related question.
- **explain_query** — Explain how MetricsQL query works
- **label_values** — List of label values from VictoriaMetrics instance for a provided label name. This tool uses `/api/v1/label/{labelName}/values` endpoint of VictoriaMetrics API.
- **labels** — List of label names of the VictoriaMetrics instance. This tools uses `/api/v1/labels` endpoint of VictoriaMetrics API.
- **metric_statistics** — Statistics of metrics usage in queries of the VictoriaMetrics instance. This tool helps to identify unused (never queried) or rarely used metrics or conversely actively queried metrics. This tool uses `/api/v1/status/metric_names_stats` endpoint of VictoriaMetrics API.
- **metrics** — List of available metrics of the VictoriaMetrics instance. This tool uses `/api/v1/label/__name__/values` endpoint of VictoriaMetrics API.
- **metrics_metadata** — Returns stored metrics details (metadata) such as name, type, help (description), and unit, and can be used to generate natural language queries. This tool uses `/api/v1/metadata` endpoint of VictoriaMetrics API.
- **prettify_query** — Prettify (format) MetricsQL query. This tool uses `/prettify-query` endpoint of VictoriaMetrics API.
- **query** — Instant query executes PromQL or MetricsQL query expression at the given time. The result of Instant query is a list of time series matching the filter in query expression. Each returned series contains exactly one (timestamp, value) entry, where timestamp equals to the time query arg, while the value contains query result at the requested time. This tool uses `/api/v1/query` endpoint of VictoriaMetrics API.
- **query_range** — Range query executes the query expression at the given [start…end] time range with the given step. The result of Range query is a list of time series matching the filter in query expression. Each returned series contains (timestamp, value) results for the query executed at start, start+step, start+2*step, …, start+N*step timestamps. In other words, Range query is an Instant query executed independently at start, start+step, …, start+N*step timestamps with the only difference that an instant query does not return ephemeral samples (see below). Instead, if the database does not contain any samples for the requested time and step, it simply returns an empty result. This tool uses `/api/v1/query_range` endpoint of VictoriaMetrics API.
- **rules** — List of alerting and recording rules of VictoriaMetrics instance. This tool uses `/api/v1/rules` endpoint of vmalert API proxied by VictoriaMetrics API.
- **series** — List of available time series of the VictoriaMetrics instance. This tool uses `/api/v1/series` endpoint of VictoriaMetrics API.
- **tenants** — List of tenants of the VictoriaMetrics instance.  This tool uses `/admin/tenants` endpoint of VictoriaMetrics API.
- **top_queries** — Top queries.
This tool can determine top queries of the following query types:
- the most frequently executed queries;
- queries with the biggest average execution duration;
- queries that took the most summary time for execution.
This information is obtained from the "/api/v1/status/top_queries" HTTP endpoint of VictoriaMetrics API.

- **tsdb_status** — The following tool returns various cardinality statistics about the VictoriaMetrics TSDB:
- Metric names with the highest number of series.
- Labels with the highest number of series.
- Values with the highest number of series for the selected label (aka focusLabel).
- label=name pairs with the highest number of series.
- Labels with the highest number of unique values.

This tool returns TSDB stats from "/api/v1/status/tsdb" endpoint of VictoriaMetrics API (in the way similar to Prometheus).


## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "mcp-victoriametrics": {
    "url": "https://play-mcp.victoriametrics.com/mcp"
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/mcp-victoriametrics/readme_

