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.

Related MCP server: mcp-victoriametrics

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:

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.

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/secrets/vmanomaly-token"

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

Security

Treat an MCP client as an operator of every enabled tool. The server forwards requests to vmanomaly with the process-wide bearer token and headers configured at startup; it does not add an independent user identity or authorization boundary.

Use one of these routing models while preserving the invariant that each tool call reaches only the caller's trusted-domain vmanomaly installation:

• A local per-user stdio process may use that user's token as its configured upstream token.

• A remote MCP instance dedicated to one trusted domain may use a domain-scoped service token.

• A shared remote MCP requires per-request forwarding of a verified user token so the gateway can route each call to the correct trusted domain. The current process-wide token configuration does not implement this pass-through mode; do not place multiple untrusted domains behind one static MCP credential.

• Prefer stdio for a local, single-user integration. It has no network listener and inherits access control from the process that launches it.

• HTTP and SSE transports do not provide built-in client authentication. Keep the default loopback bind where possible. If remote access is required, place the server behind an authenticated TLS reverse proxy such as vmauth, restrict the network path, and do not expose /mcp, /sse, or /message directly to an untrusted network.

• Keep /metrics on an internal monitoring network or protect it at the proxy; health endpoints can be exposed only as required by the deployment platform.

• Give the configured vmanomaly credential the least privilege and trusted-domain scope available. Prefer VMANOMALY_BEARER_TOKEN_FILE for mounted secrets; never put tokens in command-line arguments, image layers, or committed client configuration.

• Treat VMANOMALY_HEADERS as trusted operator configuration. Tools that set pass_auth_headers=true can ask vmanomaly to forward authorization to a datasource, so permit that only for approved datasource origins and enforce an outbound network policy.

• Use MCP_ENABLED_TOOLS as a deployment allowlist. Both the allowlist and denylist are enforced for discovery and direct invocation, so hidden tools cannot be called by name. An empty allowlist retains backward compatibility by enabling every registered tool.

• MCP_DISABLE_RESOURCES=true hides resource discovery and reads. The documentation-search tool remains independent and can be separately disabled with the tool policy.

• Logs and metrics intentionally omit tool arguments/results, raw errors, client metadata, and resource URIs. Treat MCP responses and downstream vmanomaly logs as sensitive nevertheless.

These controls reduce the MCP server's exposure but do not create tenant isolation. Treat one logical vmanomaly installation, including its replicas or shards, as one trusted domain. Route mutually untrusted domains to separate installations through vmauth or another authenticated gateway. Users inside one trusted domain share its task and resource boundary.

Report suspected vulnerabilities using the private process in SECURITY.md.

Setup in clients

Cursor

Go to: Settings → Cursor Settings → MCP → Add new global MCP server and paste the following configuration into your Cursor ~/.cursor/mcp.json file:

{
  "mcpServers": {
    "vmanomaly": {
      "command": "/path/to/mcp-vmanomaly",
      "env": {
        "VMANOMALY_ENDPOINT": "http://localhost:8490",
        "VMANOMALY_BEARER_TOKEN": "<YOUR_TOKEN>",
        "VMANOMALY_HEADERS": "X-Custom=value1,X-Auth=value2"
      }
    }
  }
}

See Cursor MCP docs for more info.

Claude Desktop

Add this to your Claude Desktop claude_desktop_config.json file (you can find it if open Settings → Developer → Edit config):

{
  "mcpServers": {
    "vmanomaly": {
      "command": "/path/to/mcp-vmanomaly",
      "env": {
        "VMANOMALY_ENDPOINT": "http://localhost:8490",
        "VMANOMALY_BEARER_TOKEN": "<YOUR_TOKEN>",
        "VMANOMALY_HEADERS": "X-Custom=value1,X-Auth=value2"
      }
    }
  }
}

See Claude Desktop MCP docs for more info.

Claude Code

Run the command:

claude mcp add vmanomaly -- /path/to/mcp-vmanomaly \
  -e VMANOMALY_ENDPOINT=http://localhost:8490 \
  -e VMANOMALY_BEARER_TOKEN=<YOUR_TOKEN> \
  -e VMANOMALY_HEADERS="X-Custom=value1,X-Auth=value2"

See Claude Code MCP docs for more info.

Visual Studio Code

Add this to your VS Code MCP config file:

{
  "servers": {
    "vmanomaly": {
      "type": "stdio",
      "command": "/path/to/mcp-vmanomaly",
      "env": {
        "VMANOMALY_ENDPOINT": "http://localhost:8490",
        "VMANOMALY_BEARER_TOKEN": "<YOUR_TOKEN>",
        "VMANOMALY_HEADERS": "X-Custom=value1,X-Auth=value2"
      }
    }
  }
}

See VS Code MCP docs for more info.

Zed

Add the following to your Zed config file:

  "context_servers": {
    "vmanomaly": {
      "command": {
        "path": "/path/to/mcp-vmanomaly",
        "args": [],
        "env": {
          "VMANOMALY_ENDPOINT": "http://localhost:8490",
          "VMANOMALY_BEARER_TOKEN": "<YOUR_TOKEN>",
          "VMANOMALY_HEADERS": "X-Custom=value1,X-Auth=value2"
        }
      },
      "settings": {}
    }
  }

See Zed MCP docs for more info.

JetBrains IDEs

• Open Settings → Tools → AI Assistant → Model Context Protocol (MCP).

• Click Add (+)

• Select As JSON

• Put the following to the input field:

{
  "mcpServers": {
    "vmanomaly": {
      "command": "/path/to/mcp-vmanomaly",
      "env": {
        "VMANOMALY_ENDPOINT": "http://localhost:8490",
        "VMANOMALY_BEARER_TOKEN": "<YOUR_TOKEN>",
        "VMANOMALY_HEADERS": "X-Custom=value1,X-Auth=value2"
      }
    }
  }
}

Windsurf

Add the following to your Windsurf MCP config file:

{
  "mcpServers": {
    "vmanomaly": {
      "command": "/path/to/mcp-vmanomaly",
      "env": {
        "VMANOMALY_ENDPOINT": "http://localhost:8490",
        "VMANOMALY_BEARER_TOKEN": "<YOUR_TOKEN>",
        "VMANOMALY_HEADERS": "X-Custom=value1,X-Auth=value2"
      }
    }
  }
}

See Windsurf MCP docs for more info.

Using Docker instead of binary

You can run vmanomaly MCP server using Docker instead of local binary.

You should replace run command in configuration examples above in the following way:

{
  "mcpServers": {
    "vmanomaly": {
      "command": "docker",
      "args": [
        "run",
        "-i", "--rm",
        "-e", "VMANOMALY_ENDPOINT",
        "-e", "VMANOMALY_BEARER_TOKEN",
        "-e", "VMANOMALY_HEADERS",
        "ghcr.io/victoriametrics/mcp-vmanomaly"
      ],
      "env": {
        "VMANOMALY_ENDPOINT": "http://localhost:8490",
        "VMANOMALY_BEARER_TOKEN": "<YOUR_TOKEN>",
        "VMANOMALY_HEADERS": "X-Custom=value1,X-Auth=value2"
      }
    }
  }
}

Usage

After installing and configuring the MCP server, you can start using it with your favorite MCP client.

You can start dialog with AI assistant from the phrase:

Use MCP vmanomaly in the following answers

But it's not required, you can just start asking questions and the assistant will automatically use the tools and documentation to provide you with the best answers.

Toolset

MCP vmanomaly provides tools organized into categories:

Health & Info (4 tools)

Deployment sizing (3 tools)

Peer-pool sizing is experimental and requires backend support: use model_class: peer_outlier, options.topology: wide and options.channels_per_entity for peers per pool. Forward entity_count counts pools; reverse capacity counts pool-models, with peer-series count returned separately. For example, two five-peer pools are two entities and ten input series. Initial support is limited to equal-size fixed pools (3–10,000 peers, meeting min_peer_count, default 5), complete observations, one query per workload and no churn retention. Omit model_params.groupby; declare separate forward workloads for distinct queries or pool sizes. Do not average unequal pools or replace an unsupported peer estimate with univariate sizing. No peer profile is initially shipped; bounded live calibration requires the installed backend version. Pool widths above 64 use bounded-sample n log(n) CPU and linear memory/output approximations. Shared fallback worker coefficients are not peer-specific measurements. Keep the user's requested pool width; never substitute a smaller pool. Estimates need representative validation.

Currently experimental as of vmanomaly v1.31.0; requires a server exposing the deployment-sizing API. Earlier targets are unsupported; an omitted target uses the installed server version. Report any version fallback returned by the server without claiming validation on the requested release. Deployment sizing estimates resources for vmanomaly itself, rather than forecasting a monitored metric with forecast_at.

Forward sizing accepts workloads, each with model_class, entity_count and infer_every_seconds. Reverse sizing needs model_class, cpus and infer_every_seconds; ram_limit_bytes is optional. Each accepts an options object for the corresponding backend fields, with workload-specific options nested in each workload. For example:

{"model_class":"mad_online","cpus":2,"infer_every_seconds":300,"ram_limit_bytes":2147483648,"options":{"vmanomaly_version":"v1.31.0","infer_points_per_cycle":2}}

Choose the flow by the unknown: a known series count needs forward sizing; fixed CPU/RAM and cadence with no count needs reverse sizing, even if the user simply asks for "capacity". Do not request cardinality for reverse sizing. The output is active model/entity count: univariate entities are series, multivariate entities are groups. Supply topology and channels_per_entity for multivariate requests and report input_series separately. Missing history can be clarified or explicitly defaulted. Compare memory and disk with otherwise identical inputs. In reverse sizing, an explicit numeric history.step_seconds defaults the scored batch to ceil(infer_every_seconds / step_seconds) unless infer_points_per_cycle is supplied. MCP reports this non-overlapping-cycle assumption alongside successful and failed sizing results.

For online models, forward sizing automatically treats fit duration as advisory against inference cadence; fit peak RAM/disk still count. Provide history window/step and omit fit_every_seconds unless the user requests periodic refits. Never infer refit cadence from fit_window. mad/mad_online and zscore/zscore_online resolve to the same online classes. An explicit finite interval includes recurring compute. Batch models keep hard fit deadlines and default to daily fitting. Use explicit options.deployment.members_count and split_by=queries for a fixed query-shard layout.

Results preserve resolved inputs, stage costs, resource constraints and operational warnings, with a single experimental-estimate notice. Internal calibration diagnostics are omitted from forward/reverse tool results; profile discovery is returned unchanged. Reverse sizing covers inference only, excluding bootstrap/refits/churn. Check the model schema or profile before supplying required parameters; do not invent them. Unsupported seasonal configurations require a matching profile or offline calibration, rather than fewer series or a different cadence.

Requests use the existing authenticated backend client, fixed routes, bounded request bodies and a bounded cancelable queue. The request timeout includes waiting, and profile discovery remains independent. Backend validation and overload errors are returned as tool errors without automatic retries; the session can accept a corrected follow-up. Older servers may not expose these routes. These tools do not change a running deployment.

Forward sizing resolves omitted scored points from explicit sampling and cadence, and defaults the inference deadline to the shortest workload cadence. Explicit overrides are preserved. An infeasible explicit deployment returns binding constraints; the adapter does not retry or substitute a balanced repartition. Compare CPU candidates in one call, and keep nominal versus margin-adjusted times distinct.

Model Configuration (4 tools)

Configuration (1 tool)

Documentation (1 tool)

Compatibility (1 tool)

Alerting (1 tool)

Analysis & Autotune (4 tools)

vmanomaly_create_autotune_task accepts optimization_n_trials, optimization_timeout, and advanced optimization_params to bound Optuna work. The MCP tool uses interactive defaults of 32 trials and 8 seconds when no optimization budget is provided, and a conservative anomaly fraction of 0.02 when anomaly_percentage is omitted; the vmanomaly API defaults are larger. Poll vmanomaly_get_autotune_task until status is done, then use the recommendation under result_data. Treat error and canceled as terminal statuses.

The running server's list/schema endpoints expose UI-compatible models, not an exhaustive catalog of every deployable model. Their contents depend on the server version; servers supporting the corresponding investigation views can include multivariate and peer-group models. Check the returned list and schema rather than assuming those models are always present or always excluded.

For multivariate detection, tune the multivariate class directly with aligned named queries and any frozen_params.groupby labels; the result uses a joint anomaly score. Documented models not exposed by an older server's UI endpoints may still support server-side tuning and complete configuration validation; verify that server's capabilities before using them or suggesting them in VMUI.

With vmanomaly 1.31.0+, shared tuning accepts peer_outlier. Keep entity labels in query results and supply population grouping in frozen_params.groupby; queries remain separate populations. Stable query policies remain authoritative. The tuning result is a concrete model configuration: deployment sizing can estimate that model's fit/inference resources, not the auto wrapper's search cost. Supervised marking is available in VMUI; the current MCP tuning tool exposes the unsupervised objective, not label submission.

For new configurations, prefer online models. Prophet, Holt-Winters, and Isolation Forest remain supported for existing deployments but are planned for future deprecation; use Temporal Envelope as the corresponding univariate or multivariate migration target.

Dialog example

This example shows data-driven model selection rather than choosing a model from the metric name. The YAML is a complete deployment-config excerpt: VMUI suggestion cards continue to carry business-policy fields in the model configuration because the UI query editor currently exposes only the query expression and language.

• You: Detect sustained CPU spikes for avg by (instance) (1 - rate(node_cpu_seconds_total{mode="idle"}[5m])) at a 5m step.

• Assistant: I profiled the exact query first. The sampled series contain a trend and recurring hour-of-day/day-of-week structure, so temporal_envelope is the best online starting point. If the profile had no meaningful trend or seasonality, I would prefer mad_online for robust data, or zscore_online only for a stable light-tailed distribution.

• Assistant: I verified the model and schema, then started shared autotune with the same 5m step, anomaly_percentage=0.02, and causal exact=true validation. After sequentially polling the task to completion, I validated the returned model configuration before presenting it.

  reader:
    workers: 0
    queries:
      cpu_non_idle:
        expr: avg by (instance) (1 - rate(node_cpu_seconds_total{mode="idle"}[5m]))
        detection_direction: above_expected
        min_rel_dev_from_expected: [0, 15]
  
  models:
    cpu_envelope:
      class: temporal_envelope
      queries: [cpu_non_idle]
      schedulers: [cpu_5m]
      seasonalities: [hod_smooth, dow_smooth]

  The exact tuned parameters depend on the sampled data; the final model spec is always validated against the running vmanomaly instance.

During this dialog, the assistant used the following tools:

• vmanomaly_timeseries_characteristics to measure the sampled data profile

• vmanomaly_list_models and vmanomaly_get_model_schema to verify the UI-compatible model

• vmanomaly_create_autotune_task and vmanomaly_get_autotune_task to tune shared parameters

• vmanomaly_validate_model_config to validate the tuned model

• vmanomaly_validate_config to validate the configuration

Monitoring

In HTTP and SSE modes the MCP Server provides metrics in Prometheus format at the /metrics endpoint.

Tracked operations:

• mcp_vmanomaly_initialize_total - Client connections

• mcp_vmanomaly_call_tool_total{name,is_error} - Tool calls with success/error tracking

• mcp_vmanomaly_read_resource_total - Documentation resource reads

• mcp_vmanomaly_list_*_total - List operations (tools, resources, prompts)

• mcp_vmanomaly_error_total{method,error_class} - Errors by bounded, non-sensitive class

Example:

# Start in HTTP mode
VMANOMALY_ENDPOINT="http://localhost:8490" MCP_SERVER_MODE=http ./bin/mcp-vmanomaly

# Query metrics
curl http://localhost:8080/metrics

Roadmap

• Grafana dashboard for MCP server monitoring

• Add API compatibility matrix to gracefully handle version differences between MCP client and vmanomaly server (API is evolving, features may be unavailable)

Disclaimer

AI services and agents along with MCP servers like this cannot guarantee the accuracy, completeness and reliability of results. You should double check the results obtained with AI.

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.

Contributing

Contributions to the MCP vmanomaly project are welcome!

Please feel free to submit issues, feature requests, or pull requests.

Related Projects

• vmanomaly - VictoriaMetrics anomaly detection

• VictoriaMetrics - Time series database

• mcp-victoriametrics - MCP server for VictoriaMetrics

• Model Context Protocol - MCP specification

Support

For vmanomaly-specific questions, see the vmanomaly documentation.

For MCP server issues, please open an issue in this repository.