MCP Server for vmanomaly

The implementation of Model Context Protocol (MCP) server for vmanomaly - VictoriaMetrics Anomaly Detection product.

This provides seamless integration with vmanomaly REST API and documentation for AI-assisted anomaly detection, model management, and observability insights.

Features

This MCP server enables AI assistants like Claude to interact with vmanomaly for:

• Health Monitoring: Check vmanomaly server health and build information
• Model Management: Discover UI-compatible models and validate univariate or multivariate configurations
• Data-Driven Recommendations: Profile sampled time series and run shared autotune suggestions for one production-ready model config across many returned series
• Configuration Generation: Generate complete vmanomaly YAML configurations
• Alert Rule Generation: Generate vmalert alerting rules based on anomaly score metrics to simplify alerting setup
• Documentation Search: Full-text search across embedded vmanomaly documentation with fuzzy matching

The MCP server contains embedded up-to-date vmanomaly documentation and is able to search it without online access.

The quality of the MCP Server and its responses depends very much on the capabilities of your client and the quality of the model you are using.

Requirements

• vmanomaly instance with REST API access:
  • version 1.28.3+ for the core MCP toolset
  • version 1.30.0+ for time-series characteristics and task-based shared autotune
  • version 1.30.5+ for named-query shared autotune and query-policy suggestions in VMUI
  • version 1.31.0+ for experimental peer-group tuning and deployment sizing
• Go 1.26.9 or higher (if building from source)

Installation

Go

go install github.com/VictoriaMetrics/mcp-vmanomaly/cmd/mcp-vmanomaly@vX.Y.Z

Replace vX.Y.Z with the exact release you have reviewed.

Binaries

Download the latest release from Releases page and put it to your PATH.

Example for Linux x86_64 (other architectures and platforms are also available). Select an explicit release rather than a mutable latest URL, verify its checksum, and then verify its GitHub build-provenance attestation:

version=vX.Y.Z
archive=mcp-vmanomaly_Linux_x86_64.tar.gz
curl -fLO "https://github.com/VictoriaMetrics/mcp-vmanomaly/releases/download/${version}/${archive}"
curl -fLO "https://github.com/VictoriaMetrics/mcp-vmanomaly/releases/download/${version}/checksums.txt"
grep "  ${archive}$" checksums.txt | sha256sum --check -
gh attestation verify "${archive}" --repo VictoriaMetrics/mcp-vmanomaly
tar axvf "${archive}"
./mcp-vmanomaly --version

Build-provenance attestations are available for releases produced by the hardened release workflow. Release tags must be annotated, cryptographically signed, and marked as verified by GitHub before that workflow publishes artifacts.

Docker

You can run vmanomaly MCP Server using Docker.

This is the easiest way to get started without needing to install Go or build from source.

docker run -d --name mcp-vmanomaly \
  --add-host=host.docker.internal:host-gateway \
  -e VMANOMALY_ENDPOINT=http://host.docker.internal:8490 \
  -e MCP_SERVER_MODE=http \
  -e MCP_LISTEN_ADDR=:8080 \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/victoriametrics/mcp-vmanomaly:vX.Y.Z

Replace vX.Y.Z and the environment variables with your own parameters. When both services run in Docker, prefer a private Docker network and use the vmanomaly service name as the endpoint.

Note that the MCP_SERVER_MODE=http flag is used to enable Streamable HTTP mode. More details about server modes can be found in the Configuration section.

See available docker images in github registry.

Also see Using Docker instead of binary section for more details about using Docker with MCP server with clients in stdio mode.

Source Code

For building binary from source code you can use the following approach:

• Clone repo:

  git clone https://github.com/VictoriaMetrics/mcp-vmanomaly.git
  cd mcp-vmanomaly
  

• Build binary from cloned source code:

  make build
  # after that you can find binary mcp-vmanomaly and copy this file to your PATH or run inplace
  

• Build image from cloned source code:

  docker build -t mcp-vmanomaly .
  # after that you can use docker image mcp-vmanomaly for running or pushing
  

  For local UI/Copilot testing from the vmanomaly repository, build with a local tag:

  docker build -t mcp-vmanomaly:local .
  

  Then run the vmanomaly repository helper with:

  MCP_VMANOMALY_IMAGE=mcp-vmanomaly:local bin/run-mcp-http.sh
  

Configuration

MCP Server for vmanomaly is configured via environment variables:

| Variable | Description | Required | Default | Allowed values | |--------------------------|---------------------------------------------------------------------------------------------------------|----------|------------------|------------------------| | VMANOMALY_ENDPOINT | vmanomaly server endpoint URL (e.g., http://localhost:8490) | Yes | - | - | | VMANOMALY_BEARER_TOKEN | Bearer token for authenticating with vmanomaly API (mutually exclusive with the token file) | No | - | - | | VMANOMALY_BEARER_TOKEN_FILE | Path to a bearer-token file, suitable for mounted container/orchestrator secrets | No | - | - | | VMANOMALY_HEADERS | Custom HTTP headers for requests (comma-separated key=value pairs, e.g., X-Custom=value1,X-Auth=value2) | No | - | - | | VMANOMALY_REQUEST_TIMEOUT | HTTP timeout for calls from MCP to vmanomaly, e.g. 60s | No | 30s | - | | MCP_SERVER_MODE | Server operation mode. See Modes for details. | No | stdio | stdio, http, sse | | MCP_LISTEN_ADDR | Address for HTTP server to listen on | No | localhost:8080 | - | | MCP_ENABLED_TOOLS | Positive comma-separated tool allowlist; empty enables all registered tools | No | - | - | | MCP_DISABLED_TOOLS | Comma-separated tool denylist; takes precedence over the allowlist | No | - | - | | MCP_DISABLE_RESOURCES | Disable all resources (documentation search will continue to work) | No | false | false, true | | MCP_HEARTBEAT_INTERVAL | Heartbeat interval for streamable-http protocol (keeps connection alive through network infrastructure) | No | 30s | - | | MCP_LOG_LEVEL | Log level: debug (verbose), info (default), warn, or error | No | info | - | | MCP_LOG_FILE | Log file path (empty = stderr) | No | stderr | - |

Modes

MCP Server supports the following modes of operation (transports):

• stdio - Standard input/output mode, where the server reads commands from standard input and writes responses to standard output. This is the default mode and is suitable for local servers.
• http - Streamable HTTP. Server will expose the /mcp endpoint for HTTP connections.
• sse - Server-Sent Events. Server will expose the /sse and /message endpoints for SSE connections.

[!NOTE] The sse transport mode was officially deprecated from MCP Specification (version 2025-03-26) and was replaced by Streamable HTTP transport (http mode). In future releases its support can be deprecated, use Streamable HTTP transport if your client supports it.

More info about transports you can find in MCP docs:

• Core concepts → Transports
• Specifications → Transports

Configuration examples

# Basic configuration
export VMANOMALY_ENDPOINT="http://localhost:8490"

# With authentication
export VMANOMALY_ENDPOINT="http://localhost:8490"
export VMANOMALY_BEARER_TOKEN="your-token"

# Or load the token from a mounted secret file
export VMANOMALY_BEARER_TOKEN_FILE="/run…[redacted]"

# With custom headers (e.g., behind a reverse proxy)
export VMANOMALY_HEADERS="X-Custom-Header=value1,X-Another=value2"

# Expose only the tools required by this deployment. A denylist can further
# narrow this set and always takes precedence.
export MCP_ENABLED_TOOLS="vmanomaly_health_check,vmanomaly_search_docs"
export MCP_DISABLED_TOOLS="vmanomaly_get_metrics"

# Server mode
export MCP_SERVER_MODE="http"
export MCP_LISTEN_ADDR="0.0.0.0:8080"

# Logging
export MCP_LOG_LEVEL="debug"
export MCP_LOG_FILE="/tmp/mcp-vmanomaly.log"

Endpoints

In HTTP and SSE modes the MCP server provides the following endpoints:

| Endpoint | Description | |----------------------|--------------------------------------------------------------------------------------------------| | /mcp | HTTP endpoint for streaming messages in HTTP mode (for MCP clients that support Streamable HTTP) | | /metrics | Metrics in Prometheus format for monitoring the MCP server | | /health/liveness | Liveness check endpoint to ensure the server is running | | /health/readiness | Readiness check endpoint to ensure the server is ready to accept requests | | `/ss