
Mcp Vmanomaly
io.github.VictoriaMetrics-Community由 GitHub 账号 VictoriaMetrics-Community 发布v0.1.0更新于 Nov 10, 2026
MCP Server for vmanomaly - VictoriaMetrics anomaly detection
概览
将助手连接到 VictoriaMetrics vmanomaly 实例,用于健康检查、异常检测模型调优、生成配置与告警规则,并检索内置文档。
- 可以做什么
- 检查 vmanomaly 健康状态、构建信息、服务器查询与 Prometheus 指标
- 发现指标并采样时间序列,给出自动调优建议
- 校验模型配置并生成完整的 vmanomaly YAML 配置
- 生成 vmalert 告警规则与预设产物,包括 Compose、Helm 和 Operator 部署文件
- 估算部署资源与推理容量
- 离线全文检索内置的 vmanomaly 文档
- 适用场景
- 当你用 vmanomaly 对 VictoriaMetrics 数据做异常检测,并希望助手协助规划部署规模、选择与调优模型、编写配置和告警规则,或在无网络时查阅 vmanomaly 文档时适用。
- 运行要求
- 需要一个可访问且开放 REST API 的 vmanomaly 实例(核心工具需 1.28.3+,指标发现、容量估算和预设产物需更新版本),通过 VMANOMALY_ENDPOINT 指定。以本地二进制、Go 安装或容器镜像运行;仅从源码构建时需要 Go 1.26.10+。可选 VMANOMALY_BEARER_TOKEN 或 VMANOMALY_BEARER_TOKEN_FILE、自定义请求头和 TLS 设置。
安装
在 SourceWeft 中
- 打开 控制台中的 Mcp Vmanomaly,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
MCP Server for vmanomaly
[Latest Release] [License] [Slack] [X]
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
vmanomalyserver 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
vmanomalyYAML configurations - Alert Rule Generation: Generate
vmalertalerting rules based on anomaly score metrics to simplify alerting setup - Documentation Search: Full-text search across embedded
vmanomalydocumentation 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
vmanomalyinstance 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 schedule replay in shared autotune, experimental peer-group tuning and deployment sizing
- version 1.32.0+ for metric discovery and dynamic preset artifacts, including Compose, Helm and VM Operator deployment files
- Go 1.26.10 or higher (if building from source)
Installation
Go
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:
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.
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:
-
Build binary from cloned source code:
-
Build image from cloned source code:
For local UI/Copilot testing from the vmanomaly repository, build with a local tag:
Then run the vmanomaly repository helper with:
Configuration
MCP Server for vmanomaly is configured via environment variables:
Connecting to vmanomaly over HTTPS
Use an https:// URL in VMANOMALY_ENDPOINT. Server certificates are verified against the system trust store. For a private CA, set VMANOMALY_TLS_CA_FILE, or VMANOMALY_TLS_CA_CERT with the PEM content when the runtime cannot mount files; the CA is added to the system roots. When vmanomaly requires client certificates (mutual TLS), also set VMANOMALY_TLS_CERT_FILE and VMANOMALY_TLS_KEY_FILE. VMANOMALY_TLS_INSECURE_SKIP_VERIFY=true disables server certificate verification and cannot be combined with a custom CA; use it only for development or testing. Certificates are read at startup, so restart the server after rotating them.
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/mcpendpoint for HTTP connections.sse- Server-Sent Events. Server will expose the/sseand/messageendpoints for SSE connections.
[!NOTE] The
ssetransport mode was officially deprecated from MCP Specification (version 2025-03-26) and was replaced by Streamable HTTP transport (httpmode). 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:
Configuration examples
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
stdioprocess 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
stdiofor 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/messagedirectly to an untrusted network. -
Keep
/metricson 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_FILEfor mounted secrets; never put tokens in command-line arguments, image layers, or committed client configuration. -
Treat
VMANOMALY_HEADERSas trusted operator configuration. Tools that setpass_auth_headers=truecan 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_TOOLSas 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=truehides 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:
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):
See Claude Desktop MCP docs for more info.
Claude Code
Run the command:
See Claude Code MCP docs for more info.
Visual Studio Code
Add this to your VS Code MCP config file:
See VS Code MCP docs for more info.
Zed
Add the following to your Zed config file:
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:
Windsurf
Add the following to your Windsurf MCP config file:
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:
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:
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:
Bounded metric discovery
vmanomaly_discover_metrics calls the additive POST /api/v1/discovery API. Requires vmanomaly 1.32.0+; treat 404 as unsupported. Supply a datasource, optional explicit tenant, selectors and a fixed window. Tenant scope may be numeric (accountID or accountID:projectID) or explicitly multitenant, including a /select/multitenant/prometheus datasource URL; conflicting URL/request tenants are rejected by the discovery API. Multitenant metadata reads require VictoriaMetrics v1.104.0 or newer and a discovery API version that accepts this scope. Preserve vm_account_id/vm_project_id selectors and returned series labels; never automatically broaden a numeric tenant scope. Metric/label inventories across tenants do not establish per-tenant coverage. Each call performs one metadata request; no historical samples, retries or tenant enumeration. Defaults are 100 results and 10 seconds; maxima are 1,000 results, 10 selectors, 31 days and 30 seconds. The MCP client caps response bytes but does not limit concurrent discovery calls; server-side admission limits depend on the deployed backend. These caps do not bound the TSDB index scan. Preserve upstream warnings and completeness; returned counts are neither total cardinality nor exact historical coverage.
Preset configuration and alert artifacts
vmanomaly_generate_preset_artifacts calls the additive POST /api/v1/preset/artifacts API. Requires vmanomaly 1.32.0+; treat 404 as unsupported. Supply a complete configuration with explicit reader and VictoriaMetrics writer destinations, models and schedulers. Optional alert policy controls threshold, evaluation interval, persistence and the externally reachable incident base URL. entity_labels contains only known source labels; omit it for query-group links. Results retain structured configuration/rules, equivalent YAML, schema version and warnings. The request is limited to 1 MiB and the response to 8 MiB.
With vmanomaly v1.32.0+, optional deployment selects targets (compose, helm, operator), storage (memory or persistent) and an explicit released image tag. Include known choices in the first generation call to receive the complete bundle once. The backend owns validation and rendering; MCP preserves the returned files, per-file requirements and warnings without rewriting them. Helm uses pinned chart 1.12.19; Operator uses v0.75.2 and supports persistent storage only. Missing license or volume details use backend-generated draft requirements; request-level required_inputs remains restricted to the two writer fields. Generation does not install anything or verify a live deployment.
Generation is read-only. schema-valid does not establish data coverage, sizing, connectivity, alert delivery or deployment readiness. The existing configuration and example-rule tools remain available; a successful validation response describes schema validation only. Use separate rendering and live checks before deployment.
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:
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)
For schedule-aware tuning, optionally pass replay: {"fit_window":"3d", "fit_every":"1000w", "infer_every":"5m"} together with fixed start/end Unix timestamps and the production sampling step. The backend fetches preceding training history and evaluates that inference range with the requested schedule. For causal online updates, also set optimization_params.exact: true. Omitting replay preserves fold-based tuning. The backend owns duration parsing and schedule validation.
Replay requires vmanomaly 1.31.0+. Check that the completed result_data.data.optimization.replay matches the requested schedule; older backends may ignore unknown fields. Missing/mismatched replay metadata is not schedule validation. Preserve errors rather than retrying without replay. This evaluated range was used for tuning: validate the selected configuration on a separate later holdout before claiming generalization or reduced false positives.
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 a5mstep. -
Assistant: I profiled the exact query first. The sampled series contain a trend and recurring hour-of-day/day-of-week structure, so
temporal_envelopeis the best online starting point. If the profile had no meaningful trend or seasonality, I would prefermad_onlinefor robust data, orzscore_onlineonly for a stable light-tailed distribution. -
Assistant: I verified the model and schema, then started shared autotune with the same
5mstep,anomaly_percentage=0.02, and causalexact=truevalidation. After sequentially polling the task to completion, I validated the returned model configuration before presenting it.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_characteristicsto measure the sampled data profilevmanomaly_list_modelsandvmanomaly_get_model_schemato verify the UI-compatible modelvmanomaly_create_autotune_taskandvmanomaly_get_autotune_taskto tune shared parametersvmanomaly_validate_model_configto validate the tuned modelvmanomaly_validate_configto 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 connectionsmcp_vmanomaly_call_tool_total{name,is_error}- Tool calls with success/error trackingmcp_vmanomaly_read_resource_total- Documentation resource readsmcp_vmanomaly_list_*_total- List operations (tools, resources, prompts)mcp_vmanomaly_error_total{method,error_class}- Errors by bounded, non-sensitive class
Example:
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.
Preset workflow guide
For preset requests, retrieve vmanomaly_get_preset_guide before choosing tools. MCP initialization advertises this routing instruction. The read-only, no-argument tool returns the complete guide and version/source/SHA-256 metadata without network or backend access. Clients with resource support can read vmanomaly://guides/preset/v1; resources do not execute automatically.
The canonical source is plugins/vmanomaly/skills/vmanomaly-preset/references/copilot-preset-guide-v1.md in VictoriaMetrics/skills. Do not edit the embedded copy. Run python3 scripts/sync-preset-guide.py /path/to/skills from a fetched canonical checkout after the skills changes merge into origin/main; --check verifies the committed snapshot and provenance. For a dependent PR only, --allow-unmerged explicitly marks review provenance; rerun without that flag from the merged skills revision before merging the MCP follow-up. The origin URL check prevents accidental misattribution, not malicious local Git metadata.
The guide lives in internal/resources/guides/, separately from release documentation search. Its tool remains available when documentation resources are disabled. It requires the discovery/artifact capabilities for that workflow, but retrieving it works offline. Instructions establish workflow budgets, not runtime enforcement. Successful artifact results become download cards only in clients implementing that renderer. Unknown writer settings default to draft generation using a .invalid URL and required_inputs (writer URL and/or tenant). Never probe placeholders. Deployment-ready requests require resolving those inputs first. Responses retain the checklist and deployment_ready: false; schema validation alone never proves readiness. No deployment is performed.
The model-selection guide is an external reference, not bundled content. Search installed documentation for related model details; do not assume this page is available offline. Live schemas take precedence over static guidance.
Refreshing embedded resources
Run make update-docs for selected manuals, or bash scripts/update-docs.sh --revision <tag> for a source release tag. The resolved source commit is recorded in internal/resources/docs/snapshot.json. Refresh the preset guide separately with python3 scripts/sync-preset-guide.py /path/to/skills; its committed source revision and content hash are recorded alongside it. The model-selection page remains link-only during refreshes.
Both refreshes stage complete snapshots in repository-local tmp/resource-sync, serialize writers with a nonblocking lock, and restore the previous snapshot if publication fails. Run them before builds: directory replacement has a short absence window, and this is not a crash-atomic transaction. A failed rollback preserves the previous snapshot under that scratch directory for recovery. These maintainer scripts require Python 3.10+ on Linux/macOS; their offline regression tests run with python3 -m unittest discover -s scripts/tests -v.
The guide links to the Helm chart and VM Operator documentation. A chart's Chart.yaml identifies a version but cannot define values or render manifests by itself. Use matching release values/templates/schema or Operator CRDs when preparing those deployment formats; these links are not bundled deployment generators.
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.
来源:README.md,提交 bfc25bb
工具
0版本历史
1- v0.1.0最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分