mcp-vmanomaly

mcp-vmanomaly is an open-source implementation of a Model Context Protocol (MCP) server that bridges AI assistants (such as Claude, Cursor, VS Code Copilot, and others) with VictoriaMetrics Anomaly Detection (vmanomaly). It exposes a set of tools that let AI agents interact with a running vmanomaly instance through its REST API, covering health monitoring, model discovery and validation, YAML configuration generation, VMAlert rule generation from anomaly score metrics, time-series profiling, shared autotune tasks, and full-text documentation search with fuzzy matching. The server ships with embedded, up-to-date vmanomaly documentation so that documentation search works offline without network access. It supports three transport modes: stdio (default, for local single-user use), Streamable HTTP (exposing /mcp), and the legacy SSE transport (exposing /sse and /message). Configuration is driven entirely by environment variables, including the vmanomaly endpoint URL, bearer token (or token file for mounted secrets), custom HTTP headers, request timeout, tool allowlist/denylist, resource toggles, heartbeat interval, and log level/file. The server also exposes Prometheus-format /metrics, /health/liveness, and /health/readiness endpoints for operational monitoring. Installation options include Go install, pre-built binaries from GitHub Releases (with checksum and build-provenance attestation verification), Docker images from ghcr.io, and building from source. Client setup instructions are provided for Cursor, Claude Desktop, Claude Code, Visual Studio Code, Zed, JetBrains IDEs, and Windsurf, each with JSON configuration snippets. A Docker-based client configuration is also included for environments where running a local binary is impractical. Security guidance is extensive: the server forwards requests using a process-wide bearer token and does not implement per-user identity or tenant isolation. The documentation recommends stdio for local single-user use, authenticated TLS reverse proxies (such as vmauth) for remote HTTP/SSE access, least-privilege vmanomaly credentials, and tool allowlist/denylist enforcement. It explicitly warns against placing multiple untrusted domains behind a single static MCP credential and advises treating one logical vmanomaly installation as one trusted domain. The toolset is organized into categories: Health & Info (4 tools), Model Configuration (4 tools), Configuration validation (1 tool), Documentation search (1 tool), Compatibility check (1 tool), Alerting rule generation (1 tool), and Analysis & Autotune (4 tools). Autotune tasks accept optimization budget parameters (trials, timeout, advanced Optuna params) and return recommendations for production-ready model configurations across sampled time series. The server requires vmanomaly 1.28.3+ for the core toolset, 1.30.0+ for time-series characteristics and task-based shared autotune, and 1.30.5+ for named-query shared autotune and query-policy suggestions in VMUI. Go 1.24+ is required for building from source.