VictoriaMetrics

You can access and manage your VictoriaMetrics instance through an MCP server that exposes VictoriaMetrics read-only APIs via convenient prompts and tools. This enables fast querying, metric exploration, rule testing, documentation search, and automation workflows without complex client setups.

How to use

Connect to the public test MCP server to explore capabilities quickly. Use the available tools to query metrics, list metrics and labels, inspect time series, test alerting rules, and search embedded documentation. You can mix tool usage with prompts to build custom monitoring workflows. For example, you can query PromQL-like expressions, list available metrics, inspect label values, or fetch documentation snippets directly from the embedded docs.

How to install

# Prerequisites
- Docker (recommended for quick start) or a Go toolchain if you prefer building/running locally
- Access to the public MCP endpoint for VictoriaMetrics (optional for testing)

# Option 1: Run via Docker (recommended for quick start)
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-community/mcp-victoriametrics

# Option 2: Build from source (Go)

go install github.com/VictoriaMetrics-Community/mcp-victoriametrics/cmd/mcp-victoriametrics@latest

# Option 3: Download pre-built binaries (Linux x86_64 example)
latest=$(curl -s https://api.github.com/repos/VictoriaMetrics-Community/mcp-victoriametrics/releases/latest | grep 'tag_name' | cut -d" -f4)
wget https://github.com/VictoriaMetrics-Community/mcp-victoriametrics/releases/download/$latest/mcp-victoriametrics_Linux_x86_64.tar.gz
tar axvf mcp-victoriametrics_Linux_x86_64.tar.gz

Additional setup and configuration

This MCP server is designed to connect to VictoriaMetrics instances and expose a set of tools for querying, analyzing, and managing your metrics. You can enable or disable specific tools via environment configuration when you run the server. For public testing, you can use the provided test endpoint and start experimenting with client prompts and built-in documentation search.

Configuration and endpoints

The MCP server exposes several modes of transport and endpoints depending on how you run it. In public testing, you’ll typically interact with the HTTP streaming endpoint. The server also serves an internal health and metrics surface to monitor the MCP broker.

To start the server in HTTP mode for streaming and interaction, use the following configuration snippet if you are integrating with an MCP client that expects an HTTP transport.

Public test MCP endpoint

{
  "type": "http",
  "name": "victoriametrics_play",
  "url": "https://play-mcp.victoriametrics.com/mcp",
  "args": []
}

Available tools

query

Execute instant PromQL/MetricsQL queries to retrieve current metric values.

query_range

Execute range PromQL/MetricsQL queries over a time range to analyze metric trends.

metrics

List available metrics present in the VictoriaMetrics instance.

metrics_metadata

Retrieve stored metrics metadata such as type, help text, and units.

labels

List available label names for filtering and exploration.

label_values

List values for a specific label to understand data distribution.

series

List available time series matching given criteria.

rules

View alerting and recording rules configured in the system.

alerts

View current alerts, including firing and pending states.

flags

View non-default flags of the VictoriaMetrics instance.

metric_statistics

Get statistics about metric usage and query impact.

active_queries

View currently executing queries for monitoring and debugging.

top_queries

Identify most frequent or slowest queries to optimize performance.

tsdb_status

View TSDB cardinality and related statistics.

tenants

List available tenants in multi-tenant deployments.

documentation

Search embedded VictoriaMetrics documentation for quick references.

prettify_query

Prettify and format PromQL/MetricsQL queries for readability.

explain_query

Parse and explain how a PromQL/MetricsQL query is evaluated.

test_rules

Unit-test alerting and recording rules using vmalert tooling.

deployments

List available VictoriaMetrics Cloud deployments (Cloud users).

cloud_providers

List available cloud providers in VictoriaMetrics Cloud.

regions

List cloud regions available for deployments.

tiers

List deployment tiers in VictoriaMetrics Cloud.

access_tokens

List deployment access tokens in VictoriaMetrics Cloud.

rule_filenames

List filenames of alerting and recording rules in Cloud.

rule_file

Show content of a specific alerting or recording rule file in Cloud.