mcp-vmanomaly

# MCP Server for vmanomaly

[![Latest Release](https://img.shields.io/github/v/release/VictoriaMetrics/mcp-vmanomaly?sort=semver&label=&logo=github&labelColor=gray&color=gray)](https://github.com/VictoriaMetrics/mcp-vmanomaly/releases)
![License](https://img.shields.io/github/license/VictoriaMetrics/mcp-vmanomaly?labelColor=green&label=&link=https%3A%2F%2Fgithub.com%2FVictoriaMetrics%2Fmcp-vmanomaly%2Fblob%2Fmain%2FLICENSE)
![Slack](https://img.shields.io/badge/Join-4A154B?logo=slack&link=https%3A%2F%2Fslack.victoriametrics.com)
![X](https://img.shields.io/twitter/follow/VictoriaMetrics?style=flat&label=Follow&color=black&logo=x&labelColor=black&link=https%3A%2F%2Fx.com%2FVictoriaMetrics)

The implementation of [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [`vmanomaly`](https://docs.victoriametrics.com/anomaly-detection/) - VictoriaMetrics Anomaly Detection product.

This provides seamless integration with `vmanomaly` REST API and [documentation](https://docs.victoriametrics.com/anomaly-detection/) 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`](https://docs.victoriametrics.com/victoriametrics/vmalert/) [alerting rules](https://docs.victoriametrics.com/victoriametrics/vmalert/#alerting-rules) based on [anomaly score metrics](https://docs.victoriametrics.com/anomaly-detection/faq/#what-is-anomaly-score) 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`](https://docs.victoriametrics.com/anomaly-detection/) instance with REST API access:
  - version [1.28.3](https://docs.victoriametrics.com/anomaly-detection/changelog/#v1283)+ for the core MCP toolset
  - version [1.30.0](https://docs.victoriametrics.com/anomaly-detection/changelog/#v1300)+ for time-series characteristics and task-based shared autotune
- Go 1.24 or higher (if building from source)

## Installation

### Go

```bash
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](https://github.com/VictoriaMetrics/mcp-vmanomaly/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:

```bash
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.

```bash
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](#configuration) section.

See available docker images in [github registry](https://github.com/VictoriaMetrics/mcp-vmanomaly/pkgs/container/mcp-vmanomaly).

Also see [Using Docker instead of binary](#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:

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

- Build binary from cloned source code:

  ```bash
  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:

  ```bash
  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:

  ```bash
  docker build -t mcp-vmanomaly:local .
  ```

  Then run the vmanomaly repository helper with:

  ```bash
  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](#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)](https://modelcontextprotocol.io/specification/2025-03-26/changelog#major-changes)
> 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](https://modelcontextprotocol.io/docs/concepts/transports)
- [Specifications → Transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports)

### Configuration exampl