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**: List, validate, and configure anomaly detection models (like `zscore_online`, `prophet`, and more)
- **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 (version [1.28.3](https://docs.victoriametrics.com/anomaly-detection/changelog/#v1283)+) with REST API access
- Go 1.24 or higher (if building from source)

## Installation

### Go

```bash
go install github.com/VictoriaMetrics/mcp-vmanomaly/cmd/mcp-vmanomaly@latest
```

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

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

### 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 \
  -e VMANOMALY_ENDPOINT=http://localhost:8490 \
  -e MCP_SERVER_MODE=http \
  -e MCP_LISTEN_ADDR=:8080 \
  -p 8080:8080 \
  ghcr.io/victoriametrics/mcp-vmanomaly
```

You should replace environment variables with your own parameters.

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

## 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                                                      | No       | -                | -                      |
| `VMANOMALY_HEADERS`      | Custom HTTP headers for requests (comma-separated key=value pairs, e.g., X-Custom=value1,X-Auth=value2) | No       | -                | -                      |
| `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_DISABLED_TOOLS`     | Comma-separated list of tools to disable                                                                | 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 officialy 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 examples

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

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

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

# 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                        |
| `/sse` + `/message`  | Endpoints for messages in SSE mode (for MCP clients that support SSE)                            |

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

```json
{
  "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](https