MCP Server for vmanomaly

You can deploy and use the MCP server for vmanomaly to enable AI-assisted interaction with your VictoriaMetrics anomaly detection system. This server exposes health checks, model management, configuration generation, alert rule generation, and full-text documentation search, all through the MCP protocol for seamless integration with compatible clients.

How to use

Use the MCP server with your chosen MCP client to manage anomaly detection models, generate configurations, and search documentation. Typical workflows include health checks to verify the vmanomaly instance is reachable, listing available models, validating configurations before applying them, generating complete YAML configurations for vmanomaly, and creating alerting rules that respond to anomaly scores. You can also perform full-text searches across embedded vmanomaly documentation with fuzzy matching to quickly find parameter details and usage examples.

How to install

Prerequisites you need before starting are a running vmanomaly instance (version 1.28.3 or newer) with REST API access and a Go toolchain if you choose to build from source. The following installation methods are supported.

Installation methods

Go install the MCP server binary directly from its module path.

Download the prebuilt binaries from the Releases page and place the binary in your PATH.

Run the MCP server via Docker for a quick start without installing Go or building from source.

If you prefer building from source, clone the repository and build the binary or create a Docker image from the source.

Concrete steps

Go to the command line and install or download the MCP server as you prefer.

Step-by-step using Docker (recommended for quick start)

Run the MCP server inside Docker with the proper environment variables to point to your vmanomaly instance and enable streamable HTTP mode.

Example: basic Docker run

docker run -d --name mcp-vmanomaly \
  -e VMANOMALY_ENDPOINT=http://localhost:8490 \
  -e MCP_SERVER_MODE=http \
  -e MCP_LISTEN_ADDR=:8080 \
  -p 8080:8080 \
  ghcr.io/victoriametrics/mcp-vmanomaly

Step-by-step using binary downloads

latest=$(curl -s https://api.github.com/repos/VictoriaMetrics/mcp-vmanomaly/releases/latest | grep 'tag_name' | cut -d" -f4)
wget https://github.com/VictoriaMetrics/mcp-vmanomaly/releases/download/$latest/mcp-vmanomaly_Linux_x86_64.tar.gz
tar axvf mcp-vmanomaly_Linux_x86_64.tar.gz

Available tools

vmanomaly_health_check

Check vmanomaly server health status and availability

vmanomaly_get_buildinfo

Retrieve build information such as version, build time, and Go version

vmanomaly_get_metrics

Obtain server metrics in Prometheus format

vmanomaly_list_models

List all available anomaly detection model types

vmanomaly_get_model_schema

Fetch JSON schema for a specific model type

vmanomaly_validate_model_config

Validate a proposed model configuration before use

vmanomaly_validate_config

Validate a complete vmanomaly YAML configuration

vmanomaly_search_docs

Full-text search across embedded vmanomaly documentation with fuzzy matching

vmanomaly_check_compatibility

Check if persisted state is compatible with the runtime version

vmanomaly_generate_alert_rule

Generate VMAlert YAML rules for anomaly score alerting