MCP Vmanomaly

🚀 MCP Server for vmanomaly

This project is an implementation of the Model Context Protocol (MCP) server for vmanomaly, which is VictoriaMetrics' anomaly detection application. It offers seamless integration with the vmanomaly REST API and documentation, enabling AI - assisted anomaly detection, model management, and observability insights.

🚀 Quick Start

This MCP server allows AI assistants such as Claude to interact with vmanomaly. After installing and configuring the MCP server, you can start using it with your preferred MCP client. Begin a dialog with the AI assistant using the phrase:

Use MCP vmanomaly in the following answers

However, this is not mandatory. You can simply start asking questions, and the assistant will automatically utilize the tools and documentation to provide the best answers.

✨ Features

• Health Monitoring: Check vmanomaly server health and build information.
• Model Management: List, validate, and configure anomaly detection models (over 10 model types, including zscore, prophet, mad, holtwinters, isolation_forest, etc.).
• Configuration Generation: Generate complete vmanomaly YAML configurations.
• Alert Rule Generation: Generate VMAlert rules for anomaly score alerting.
• Documentation Search: Conduct full - text search across the embedded vmanomaly documentation with fuzzy matching.

The MCP server contains the latest vmanomaly documentation and can perform searches without an internet connection. Note that the quality of the MCP Server and its responses highly depends on the capabilities of your client and the quality of the model you are using.

📦 Installation

Go

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

Binaries

Download the latest release from the Releases page and add it to your PATH. Example for Linux x86_64 (other architectures and platforms are also available):

latest=$(curl -s https://api.github.com/repos/VictoriaMetrics-Community/mcp-vmanomaly/releases/latest | grep 'tag_name' | cut -d\" -f4)
wget https://github.com/VictoriaMetrics-Community/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 the vmanomaly MCP Server using Docker. This is the easiest way to get started without installing Go or building from source.

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-community/mcp-vmanomaly

Replace the environment variables with your own parameters. The MCP_SERVER_MODE=http flag is used to enable Streamable HTTP mode. For more details about server modes, refer to the Configuration section. See available docker images in the github registry. Also, see the Using Docker instead of binary section for more details on using Docker with the MCP server and clients in stdio mode.

Source Code

To build the binary from the source code, follow these steps:

• Clone the repo:

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

• Build the binary from the cloned source code:

  make build
  # After that, you can find the binary mcp-vmanomaly and copy it to your PATH or run it in-place
  

• Build the image from the cloned source code:

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

📚 Documentation

Configuration

The MCP Server for vmanomaly is configured via environment variables:

Modes

The MCP Server supports the following operation modes (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. The server will expose the /mcp endpoint for HTTP connections.
• sse - Server - Sent Events. The server will expose the /sse and /message endpoints for SSE connections.

⚠️ Important Note

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

For more information about transports, refer to the 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"

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

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 information.

Claude Desktop

Add the following to your Claude Desktop claude_desktop_config.json file (you can find it by opening 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 information.

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 information.

Visual Studio Code

Add the following 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 information.

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 information.

JetBrains IDEs

• Open Settings → Tools → AI Assistant → Model Context Protocol (MCP).
• Click Add (+)
• Select As JSON
• Enter the following in 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 information.

Using Docker instead of binary

You can run the vmanomaly MCP server using Docker instead of a local binary. Replace the run command in the above configuration examples as follows:

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

💻 Usage Examples

Toolset

MCP vmanomaly provides tools organized into categories:

Health & Info (3 tools)

Model Configuration (3 tools)

Configuration (1 tool)

Documentation (1 tool)

Compatibility (1 tool)

Alerting (1 tool)

Dialog example

This is an example dialog demonstrating how an AI assistant can assist with vmanomaly configuration and anomaly detection:

• You: I want to set up anomaly detection for CPU usage. What models are available?

• Assistant: I can help you set up anomaly detection for CPU usage. Let me check available models in vmanomaly.

  Your vmanomaly instance supports the following anomaly detection models:

  • zscore - Statistical model based on z - score (standard deviations from mean)
  • prophet - Facebook's Prophet model for time series with seasonality
  • mad - Median Absolute Deviation model
  • holtwinters - Holt - Winters seasonal method
  • isolation_forest_univariate - Isolation Forest for univariate time series
  • rolling_quantile - Rolling quantile - based detection
  • auto - Automatic model selection

  For CPU usage monitoring, I'd recommend starting with the zscore model as it's simple, fast, and works well for metrics with stable patterns. Would you like me to generate a configuration?

• You: Yes, please generate a configuration for monitoring CPU usage with the zscore model.

• Assistant: I'll generate a complete vmanomaly configuration for CPU usage monitoring with the zscore model:

  scheduler:
    infer_every: "1m"
    fit_every: "1h"
    fit_window: "2d"
  
  reader:
    datasource_url: "http://victoriametrics:8428"
    queries:
      cpu_usage: "avg(rate(node_cpu_seconds_total{mode!='idle'}[5m])) by (instance)"
    step: "1m"
  
  models:
    zscore_cpu:
      class: "zscore"
      z_threshold: 2.5
  
  writer:
    datasource_url: "http://victoriametrics:8428"
  

  This configuration will:

  • Run inference every minute
  • Retrain the model every hour using the last 2 days of data
  • Use the z - score model with a threshold of 2.5 standard deviations
  • Monitor CPU usage across all instances

  Would you like me to validate this configuration or adjust any parameters?

• You: Looks good! Can you create a detection task to test it?

• Assistant: I'll create an anomaly detection task to test the configuration on your recent CPU data:

  Task created successfully! Here's the status:

  • Task ID: task - abc - 123
  • Status: Running
  • Model: zscore with z_threshold = 2.5
  • Time range: Last 24 hours
  • Progress: Processing data...

  The task is analyzing your CPU usage data. You can check the results in VictoriaMetrics by querying the anomaly score metrics. Would you like me to check the task status or show you how to query the results?

During this dialog, the assistant used the following tools:

• vmanomaly_list_models to get available model types
• vmanomaly_validate_config to validate the configuration
• vmanomaly_create_detection_task to start anomaly detection
• vmanomaly_search_docs to provide context about model parameters

🔧 Technical Details

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{uri} - Documentation resource reads
• mcp_vmanomaly_list_*_total - List operations (tools, resources, prompts)
• mcp_vmanomaly_error_total{method,error} - Errors by method and type

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

• [ ] Add prompts for common vmanomaly workflows (model selection, troubleshooting).
• [ ] Create a Grafana dashboard for MCP server monitoring.
• [ ] Add an API compatibility matrix to gracefully handle version differences between the MCP client and the vmanomaly server (the API is evolving, and some features may be unavailable).

📄 License

This project is licensed as shown in the License badge.

💡 Usage Tip

AI services and agents, along with MCP servers like this one, 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 highly depends 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, refer to the vmanomaly documentation. For MCP server issues, please open an issue in this repository.