mcp-victoriametrics

This VictoriaMetrics MCP Server provides an integration point for your VictoriaMetrics deployment, exposing almost all read-only VMUI capabilities through the MCP interface. You can query metrics, explore data, list and export metrics and labels, analyze alerting and recording rules, inspect instance parameters, and explore data cardinality and usage statistics. The embedded documentation and prompts allow you to search VM docs offline, making it useful for debugging, troubleshooting, and automating maintenance tasks. To get started, connect with a capable MCP client and begin issuing prompts that combine metrics queries, data exploration, and VMUI prompts. The server supports dialog-style interactions where you can chain tools, docs search, and prompts to build complex observability tasks. Example workflows include exploring a metric’s label values, testing a recording rule, or explaining a complex PromQL query with optimizations. For performance and streaming scenarios, you can enable Streamable HTTP mode by configuring MCP_SERVER_MODE appropriately in your deployment.

Prerequisites:

• A VictoriaMetrics instance (self-hosted or Cloud) reachable by the MCP server.
• Docker installed on the host (or follow Go/Binary installation if you prefer).
• Basic familiarity with Docker commands if you choose the Docker route.

Option 1: Docker (recommended for quick start)

1. Ensure Docker is installed on your host.
2. Run the MCP server with the following command (adjust endpoints as needed):

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

3. Verify the server is running and accessible at http://localhost:8080 (adjust host/port as needed).

Option 2: Go installed and build from source

1. Install Go 1.17+ (per repository requirements may be newer as of your date).
2. Build the binary:

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

3. Run the binary locally:

mcp-victoriametrics

Option 3: Binaries or Source (follow repository guidance on releases)

1. Download the latest release and place the binary in your PATH.
2. Run the binary or container as per the installation notes.

Prerequisites vary by deployment choice; choose Docker for simplicity or build from source for customization.

Notes and tips:

• Environment variables control the MCP server behavior. In Docker, you typically set VM_INSTANCE_ENTRYPOINT (the VictoriaMetrics endpoint), VM_INSTANCE_TYPE (e.g., cluster or single), MCP_SERVER_MODE (e.g., sse or http), and MCP_LISTEN_ADDR (the address the MCP server listens on).
• To enable Streamable HTTP mode, set MCP_SERVER_MODE to http as described in the configuration section of the README.
• If you run behind a reverse proxy or with TLS, ensure the MCP listener address and client configurations reflect the public URL and port.
• The MCP server exposes VMUI read-only APIs; check permissions and rate limits of your VictoriaMetrics instance when performing heavy queries.
• For testing without installing, you can use the public MCP server instance at play-mcp.victoriametrics.com and compare behaviors before deploying to production.
• If you need to customize the Docker run, refer to the repository's Docker instructions and available images in the container registry.