mcp-vmanomaly

vmanomaly 的 MCP 服务

这是 vmanomaly（VictoriaMetrics 异常检测产品）的 Model Context Protocol (MCP) 服务实现。

它可与 vmanomaly REST API 和文档无缝集成，为 AI 辅助异常检测、模型管理和可观测性洞察提供支持。

功能

此 MCP 服务支持 Claude 等 AI 助手与 vmanomaly 交互，以完成以下任务：

• 健康监控：检查 vmanomaly 服务的健康状况和构建信息
• 模型管理：发现兼容 UI 的模型，并验证单变量或多变量配置
• 数据驱动的建议：分析采样时间序列，并运行共享自动调优建议，为返回的多个序列生成一份可用于生产的模型配置
• 配置生成：生成完整的 vmanomaly YAML 配置
• 告警规则生成：根据异常分数指标生成 vmalert 告警规则，简化告警设置
• 文档搜索：在嵌入的 vmanomaly 文档中进行全文搜索，并支持模糊匹配

此 MCP 服务内嵌了最新的 vmanomaly 文档，无需联网即可搜索。

MCP 服务及其响应的质量，在很大程度上取决于客户端的能力和所用模型的质量。

要求

• 可通过 REST API 访问的 vmanomaly 实例：
  • 核心 MCP 工具集需要 1.28.3 或更高版本
  • 时间序列特征和基于任务的共享自动调优需要 1.30.0 或更高版本
  • 命名查询共享自动调优和 VMUI 中的查询策略建议需要 1.30.5 或更高版本
  • 实验性的对等组调优和部署规模规划需要 1.31.0 或更高版本
• Go 1.26.10 或更高版本（如果从源代码构建）

安装

Go

go install github.com/VictoriaMetrics/mcp-vmanomaly/cmd/[email protected]

将 vX.Y.Z 替换为你已审核的确切版本。

二进制文件

从 Releases 页面下载最新版本，并将其放入 PATH。

Linux x86_64 示例（也提供其他架构和平台的版本）。请选择明确的版本，而不要使用可能变动的 latest URL；验证其校验和后，再验证其 GitHub 构建来源证明：

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

由加固版发布工作流生成的版本会提供构建来源证明。发布标签必须经过注释和加密签名，并由 GitHub 标记为已验证，此后该工作流才会发布构建产物。

Docker

你可以使用 Docker 运行 vmanomaly MCP 服务。

这是最快捷的入门方式，无需安装 Go 或从源代码构建。

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

将 vX.Y.Z 和环境变量替换为你自己的参数。当两个服务都在 Docker 中运行时，建议使用私有 Docker 网络，并将 vmanomaly 服务名称用作端点。

请注意，使用 MCP_SERVER_MODE=http 标志可启用 Streamable HTTP 模式。 有关服务模式的更多详情，请参阅配置部分。

在 github registry中查看可用的 docker 镜像。

另请参阅使用 Docker 代替二进制文件部分，了解在 stdio 模式下使用 Docker 运行 MCP 服务并连接客户端的更多详情。

源代码

如需从源代码构建二进制文件，可以使用以下方法：

• 克隆仓库：

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

• 根据克隆的源代码构建二进制文件：

  make build
  # after that you can find binary mcp-vmanomaly and copy this file to your PATH or run inplace
  

• 根据克隆的源代码构建镜像：

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

  在 vmanomaly 仓库中进行本地 UI/Copilot 测试时，请使用本地标签构建：

  docker build -t mcp-vmanomaly:local .
  

  然后使用以下命令运行 vmanomaly 仓库辅助程序：

  MCP_VMANOMALY_IMAGE=mcp-vmanomaly:local bin/run-mcp-http.sh
  

配置

vmanomaly 的 MCP 服务通过环境变量进行配置：

变量	描述	必填	默认值	允许值
VMANOMALY_ENDPOINT	vmanomaly 服务端点 URL（例如，http://localhost:8490）	是	-	-
VMANOMALY_BEARER_TOKEN	用于通过 vmanomaly API 进行身份验证的 Bearer 令牌（不能与令牌文件同时使用）	否	-	-
VMANOMALY_BEARER_TOKEN_FILE	Bearer 令牌文件的路径，适用于挂载的容器/编排器密钥	否	-	-
VMANOMALY_HEADERS	请求的自定义 HTTP 标头（以逗号分隔的键值对，例如，X-Custom=value1,X-Auth=value2）	否	-	-
VMANOMALY_REQUEST_TIMEOUT	MCP 调用 vmanomaly 时的 HTTP 超时时间，例如 60s	否	30s	-
MCP_SERVER_MODE	服务运行模式。详情请参阅 模式。	否	stdio	stdio、http、sse
MCP_LISTEN_ADDR	HTTP 服务监听的地址	否	localhost:8080	-
MCP_ENABLED_TOOLS	以逗号分隔的正向工具允许列表；为空时启用所有已注册工具	否	-	-
MCP_DISABLED_TOOLS	以逗号分隔的工具拒绝列表；优先级高于允许列表	否	-	-
MCP_DISABLE_RESOURCES	禁用所有资源（文档搜索仍可使用）	否	false	false、true
MCP_HEARTBEAT_INTERVAL	streamable-http 协议的心跳间隔（通过网络基础设施保持连接）	否	30s	-
MCP_LOG_LEVEL	日志级别：debug（详细）、info（默认）、warn 或 error	否	info	-
MCP_LOG_FILE	日志文件路径（为空时输出到 stderr）	否	stderr	-

模式

MCP Server 支持以下运行模式（传输方式）：

• stdio - 标准输入/输出模式，服务从标准输入读取命令，并将响应写入标准输出。这是默认模式，适用于本地服务。
• http - 可流式传输的 HTTP。服务将开放 /mcp 端点以处理 HTTP 连接。
• sse - 服务器发送事件。服务将开放 /sse 和 /message 端点以处理 SSE 连接。

说明

sse 传输模式已在 MCP 规范 (版本 2025-03-26) 中正式弃用，并由可流式传输的 HTTP 传输（http 模式）取代。 未来版本可能会弃用对该模式的支持；如果客户端支持，请使用可流式传输的 HTTP 传输。

有关传输方式的更多信息，请参阅 MCP 文档：

• 核心概念 → 传输方式
• 规范 → 传输方式

配置示例

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

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

# Or load the token from a mounted secret file
export VMANOMALY_BEARER_TOKEN_FILE="/run/secrets/vmanomaly-token"

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

# Expose only the tools required by this deployment. A denylist can further
# narrow this set and always takes precedence.
export MCP_ENABLED_TOOLS="vmanomaly_health_check,vmanomaly_search_docs"
export MCP_DISABLED_TOOLS="vmanomaly_get_metrics"

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

端点

在 HTTP 和 SSE 模式下，MCP 服务提供以下端点：

端点	描述
/mcp	用于在 HTTP 模式下流式传输消息的 HTTP 端点（供支持可流式传输 HTTP 的 MCP 客户端使用）
/metrics	Prometheus 格式的指标，用于监控 MCP 服务
/health/liveness	存活检查端点，用于确认服务正在运行
/health/readiness	就绪检查端点，用于确认服务已准备好接受请求
/sse + /message	SSE 模式下用于传递消息的端点（供支持 SSE 的 MCP 客户端使用）

安全

将 MCP 客户端视为每个已启用工具的操作者。服务端使用启动时配置的进程级 Bearer 令牌和请求头，将请求转发给 vmanomaly；它不会添加独立的用户身份或授权边界。

在保留以下不变量的前提下，使用以下路由模式之一：每次工具调用都只能到达调用者所信任域中的 vmanomaly 安装实例。

• 本地的按用户划分的 stdio 进程可以将该用户的令牌用作其配置的上游令牌。

• 专用于一个信任域的远程 MCP 实例可以使用域范围的服务令牌。

• 共享远程 MCP 需要逐请求转发经过验证的用户令牌，以便网关将每次调用路由到正确的信任域。当前的进程级令牌配置不支持这种透传模式；不要在一个静态 MCP 凭据后配置多个不受信任的域。

• 本地单用户集成优先使用 stdio。它不监听网络，并继承启动它的进程的访问控制。

• HTTP 和 SSE 传输不提供内置的客户端身份验证。尽可能保留默认的回环地址绑定。如果需要远程访问，请将服务端置于经过身份验证的 TLS 反向代理（例如 vmauth）后方，限制网络路径，并且不要将 /mcp、/sse 或 /message 直接暴露给不受信任的网络。

• 将 /metrics 保留在内部监控网络中，或在代理处对其进行保护；仅在部署平台需要时才暴露健康检查端点。

• 为配置的 vmanomaly 凭据授予可用范围内的最小权限和信任域范围。对于挂载的密钥，优先使用 VMANOMALY_BEARER_TOKEN_FILE；切勿将令牌放入命令行参数、镜像层或已提交的客户端配置中。

• 将 VMANOMALY_HEADERS 视为受信任的运维人员配置。启用 pass_auth_headers=true 的工具可以要求 vmanomaly 将授权信息转发给数据源，因此仅允许其用于获批的数据源来源，并实施出站网络策略。

• 将 MCP_ENABLED_TOOLS 用作部署允许列表。允许列表和拒绝列表都会对发现和直接调用生效，因此无法通过名称调用隐藏的工具。空允许列表会为保持向后兼容而启用所有已注册工具。

• MCP_DISABLE_RESOURCES=true 会隐藏资源发现和读取。文档搜索工具独立运行，并可通过工具策略单独禁用。

• 日志和指标会有意省略工具参数和结果、原始错误、客户端元数据以及资源 URI。即便如此，仍应将 MCP 响应和下游 vmanomaly 日志视为敏感信息。

这些控制措施可以降低 MCP 服务的暴露风险，但不会建立租户隔离。将一个逻辑 vmanomaly 安装实例（包括其副本或分片）视为一个信任域。通过 vmauth 或其他经过身份验证的网关，将相互不信任的域路由到不同的安装实例。同一信任域内的用户共享其任务和资源边界。

请通过 SECURITY.md 中的私密流程报告疑似漏洞。

在客户端中设置

Cursor

前往：Settings → Cursor Settings → MCP → Add new global MCP server，然后将以下配置粘贴到 Cursor 的 ~/.cursor/mcp.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"
      }
    }
  }
}

更多信息，请参阅 Cursor MCP 文档。

Claude Desktop

将以下内容添加到 Claude Desktop 的 claude_desktop_config.json 文件中（打开 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"
      }
    }
  }
}

更多信息，请参阅 Claude Desktop MCP 文档。

Claude Code

运行以下命令：

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"

更多信息，请参阅 Claude Code MCP 文档。

Visual Studio Code

将以下内容添加到 VS Code MCP 配置文件中：

{
  "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"
      }
    }
  }
}

如需了解更多信息，请参阅 VS Code MCP 文档。

Zed

将以下内容添加到 Zed 配置文件中：

  "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": {}
    }
  }

如需了解更多信息，请参阅 Zed MCP 文档。

JetBrains IDEs

• 打开 Settings → Tools → AI Assistant → Model Context Protocol (MCP)。
• 点击 Add (+)
• 选择 As 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"
      }
    }
  }
}

Windsurf

将以下内容添加到 Windsurf MCP 配置文件中：

{
  "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 MCP 文档。

使用 Docker 代替二进制文件

你可以使用 Docker 而不是本地二进制文件运行 vmanomaly MCP 服务。

你应按以下方式替换上述配置示例中的运行命令：

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

用法

安装并配置 MCP 服务后，你就可以使用自己喜欢的 MCP 客户端了。

你可以从以下短语开始与 AI 助手对话：

Use MCP vmanomaly in the following answers

但这并非必需，你可以直接开始提问，助手会自动使用工具和文档，为你提供最佳答案。

工具集

MCP vmanomaly 提供按类别组织的工具：

有界指标发现

vmanomaly_discover_metrics 会调用新增的 POST /api/v1/discovery API。它不属于 vmanomaly 1.31.0 基线：请检查已安装的端点，并将 404 视为不受支持。提供数据源、可选的显式租户、选择器和固定时间窗口。租户范围可以是数字形式（accountID 或 accountID:projectID），也可以显式指定为 multitenant，包括使用 /select/multitenant/prometheus 数据源 URL 的情况；如果 URL 与请求中的租户不一致，发现 API 会拒绝请求。多租户元数据读取要求 VictoriaMetrics v1.104.0 或更高版本，以及支持此范围的发现 API 版本。保留 vm_account_id/vm_project_id 选择器和返回的序列标签；切勿自动扩大数字租户范围。跨租户的指标／标签清单并不能证明每个租户的数据覆盖情况。每次调用只执行一个元数据请求；不读取历史样本、不重试，也不枚举租户。默认值为 100 条结果和 10 秒；上限为 1,000 条结果、10 个选择器、31 天和 30 秒。MCP 客户端会限制响应字节数，但不会限制并发发现调用；服务端准入限制取决于已部署的后端。这些上限不会限制 TSDB 索引扫描。保留上游警告和 completeness；返回的计数既不是总基数，也不代表准确的历史覆盖情况。

预设配置和告警产物

vmanomaly_generate_preset_artifacts 会调用新增的 POST /api/v1/preset/artifacts API。它不属于 vmanomaly 1.31.0 基线：请检查端点是否受支持，并将 404 视为不受支持。提供完整配置，其中包含明确的读取器和 VictoriaMetrics 写入器目标、模型和调度器。可选的告警策略控制项包括阈值、评估间隔、持续时间以及外部可访问的事件基础 URL。entity_labels 仅包含已知的源标签；对于查询组链接，请省略此项。结果保留结构化配置／规则、等效 YAML、架构版本和警告。请求大小限制为 1 MiB，响应大小限制为 8 MiB。

生成过程是只读的。schema-valid 并不能证明数据覆盖情况、资源容量、连接性、告警送达情况或部署准备情况。现有配置和示例规则工具仍可使用；验证成功响应仅说明架构验证结果。部署前请单独执行渲染和实时检查。

健康与信息（4 个工具）

工具	描述
vmanomaly_health_check	检查 vmanomaly 服务的健康状态
vmanomaly_get_buildinfo	获取构建信息（版本、构建时间、Go 版本）
vmanomaly_get_server_queries	获取已配置的服务查询别名和表达式
vmanomaly_get_metrics	以 Prometheus 格式获取 vmanomaly 服务指标

部署规模估算（3 个工具）

对等节点池规模估算目前处于实验阶段，且需要后端支持：使用 model_class: peer_outlier、options.topology: wide 和 options.channels_per_entity 指定每个池中的对等节点数。正向估算中的 entity_count 表示池数；反向估算的容量表示池模型数，另行返回对等序列数。例如，两个各有五个对等节点的池算作两个实体和十个输入序列。初始支持仅限大小相同的固定池（3–10,000 个对等节点，满足 min_peer_count，默认值为 5）、完整观测、每个工作负载一个查询，且不保留变更记录。省略 model_params.groupby；对于不同查询或池大小，分别声明正向工作负载。不要对大小不等的池取平均，也不要用单变量规模估算替代不受支持的对等节点估算。初始版本不附带对等节点配置文件；有界实时校准需要已安装的后端版本。宽度超过 64 的池使用有界样本，以 n log(n) 估算 CPU，并以线性估算内存和输出。共享的后备工作器系数并非针对对等节点的测量值。保持用户要求的池宽；切勿改用更小的宽度。估算结果需要通过有代表性的验证。

从 vmanomaly v1.31.0 起处于实验阶段；需要服务提供部署规模估算 API。不支持更早的目标版本；未指定目标版本时使用已安装的服务版本。如果服务返回版本回退信息，应予以报告，但不要声称已在请求的版本上验证。部署规模估算针对 vmanomaly 本身的资源，而不是使用 forecast_at 预测受监控的指标。

工具	用途
vmanomaly_estimate_deployment_resources	部署 CPU／RAM／磁盘及可组合的阶段估算
vmanomaly_estimate_inference_capacity	在固定 CPU 数量下估算推理间隔内的活动模型数，可选择受 RAM 限制
vmanomaly_get_deployment_sizing_profiles	查找受支持的规模估算配置文件及其模型参数

正向规模估算接受 workloads，其中每项包含 model_class、entity_count 和 infer_every_seconds。反向规模估算需要 model_class、cpus 和 infer_every_seconds；ram_limit_bytes 为可选项。两者都接受 options 对象，用于传入相应的后端字段；特定工作负载的选项嵌套在各自的工作负载中。例如：

{"model_class":"mad_online","cpus":2,"infer_every_seconds":300,"ram_limit_bytes":2147483648,"options":{"vmanomaly_version":"v1.31.0","infer_points_per_cycle":2}}

根据未知项选择流程：已知序列数时使用正向规模估算；固定 CPU／RAM 和推理频率、但没有数量时使用反向规模估算，即使用户只是询问“容量”也如此。不要为反向规模估算索取基数。输出是活动模型／实体数量：单变量实体是序列，多变量实体是组。对于多变量请求，提供 topology 和 channels_per_entity，并单独报告 input_series。可以询问缺失的历史数据，也可以明确采用默认值。比较 memory 和 disk 时，其他输入应保持相同。在反向规模估算中，如果明确指定了数值型 history.step_seconds，则除非提供 infer_points_per_cycle，否则评分批次默认为 ceil(infer_every_seconds / step_seconds)。MCP 会在成功和失败的规模估算结果中一并报告这一非重叠周期假设。 对于在线模型，正向容量估算会自动将拟合时长视为相对于推理周期的参考值；拟合峰值 RAM/磁盘仍会计入。提供历史窗口/步长，除非用户要求定期重新拟合，否则省略 fit_every_seconds。切勿根据 fit_window 推断重新拟合周期。mad/mad_online 和 zscore/zscore_online 会解析为相同的在线类。显式设置有限间隔时，估算会包含重复计算。批处理模型仍采用严格的拟合截止时间，且默认每天拟合。对于固定的查询分片布局，请显式设置 options.deployment.members_count 和 split_by=queries。

结果会保留已解析的输入、各阶段成本、资源约束和运行警告，并附带一条实验性估算提示。正向/反向工具结果会省略内部校准诊断；配置文件发现结果保持不变。反向容量估算仅涵盖推理，不包括引导、重新拟合和变更。在提供必需参数之前，请检查模型架构或配置文件；不要自行臆造参数。不支持的季节性配置需要匹配的配置文件或离线校准，而不是减少序列数或更改周期。

请求使用现有的已认证后端客户端、固定路由、有界请求正文和有界可取消队列。请求超时包含排队等待时间，配置文件发现仍独立运行。后端验证错误和过载错误会作为工具错误返回，不会自动重试；会话可以接受经过修正的后续请求。较旧的服务端可能不提供这些路由。这些工具不会更改正在运行的部署。

正向容量估算会根据显式采样和周期解析未指定的评分点数，并默认将推理截止时间设为最短工作负载周期。显式覆盖值会予以保留。若显式部署不可行，则会返回具有限制性的约束；适配器不会重试，也不会替换为均衡分区方案。在一次调用中比较 CPU 候选方案，并区分名义耗时与计入裕量后的耗时。

模型配置（4 个工具）

工具	描述
vmanomaly_list_models	列出提供给 VMUI 和其他面向 UI 的流程使用的模型
vmanomaly_get_server_models	获取已配置的服务端模型及其查询关联项
vmanomaly_get_model_schema	获取特定模型类型的 JSON 架构
vmanomaly_validate_model_config	在使用模型配置之前对其进行验证

配置（1 个工具）

工具	描述
vmanomaly_validate_config	验证完整的 vmanomaly YAML 配置

文档（1 个工具）

工具	描述
vmanomaly_search_docs	使用模糊匹配在 vmanomaly 文档中进行全文搜索

兼容性（1 个工具）

工具	描述
vmanomaly_check_compatibility	检查持久化状态是否与运行时版本兼容

告警（1 个工具）

工具	描述
vmanomaly_generate_alert_rule	生成用于异常评分告警的 VMAlert 规则 YAML

分析与自动调优（4 个工具）

工具	描述
vmanomaly_timeseries_characteristics	分析采样查询结果的趋势、季节性、尖峰程度和间隙
vmanomaly_create_autotune_task	在采样序列上启动对指定模型类别的调优
vmanomaly_get_autotune_task	轮询自动调优进度并获取已完成的建议
vmanomaly_cancel_autotune_task	请求协作取消自动调优任务

vmanomaly_create_autotune_task 接受 optimization_n_trials、optimization_timeout 和高级参数 optimization_params，用于限制 Optuna 的工作量。如果未提供优化预算，MCP 工具会使用 32 次试验和 8 秒的交互式默认值；如果省略 anomaly_percentage，则使用较保守的异常比例 0.02；vmanomaly API 的默认值更大。轮询 vmanomaly_get_autotune_task，直到 status 为 done，然后使用 result_data 中的建议。将 error 和 canceled 视为终止状态。

运行中服务的列表／架构端点提供的是兼容 UI 的模型，而非所有可部署模型的完整目录。其内容取决于服务版本；支持相应调查视图的服务可以包含多变量模型和对等组模型。请检查返回的列表和架构，不要假设这些模型一定存在或一定不包含在其中。

对于多变量检测，请使用对齐的命名查询和任意 frozen_params.groupby 标签，直接调优多变量类别；结果使用联合异常分数。较旧服务的 UI 端点未公开的文档所列模型，仍可能支持服务端调优和完整的配置验证；在使用这些模型或在 VMUI 中推荐它们之前，请确认该服务的功能。

vmanomaly 1.31.0+ 支持共享调优中的 peer_outlier。请在查询结果中保留实体标签，并在 frozen_params.groupby 中提供总体分组；查询仍代表彼此独立的总体。稳定的查询策略仍具有权威性。调优结果是具体的模型配置：部署规模估算可以评估该模型的拟合／推理资源，而非 auto 包装器的搜索成本。VMUI 支持监督式标注；当前的 MCP 调优工具提供无监督目标，不支持提交标签。

对于新配置，优先选择在线模型。Prophet、Holt-Winters 和 Isolation Forest 仍受支持，可用于现有部署，但计划在未来弃用；相应的单变量或多变量迁移目标是 Temporal Envelope。

对话示例

此示例展示了基于数据选择模型，而非根据指标名称选择模型。此 YAML 是完整部署配置的摘录：VMUI 建议卡片仍会在模型配置中携带业务策略字段，因为 UI 查询编辑器目前仅提供查询表达式和语言。

• 你：检测以下查询在 5m 步长下持续出现的 CPU 峰值： avg by (instance) (1 - rate(node_cpu_seconds_total{mode="idle"}[5m]))。

• 助手：我首先分析了确切的查询。采样序列包含趋势和反复出现的小时与星期结构，因此 temporal_envelope 是最适合在线使用的起点。如果分析结果没有明显的趋势或季节性，我会优先选择 mad_online 来处理稳健数据；只有在分布稳定且尾部较轻时，才会选择 zscore_online。

• 助手：我验证了模型和架构，然后使用相同的 5m 步长、anomaly_percentage=0.02 和因果 exact=true 验证启动了共享自动调优。我按顺序轮询任务直至完成，然后在展示返回的模型配置前对其进行了验证。

  reader:
    workers: 0
    queries:
      cpu_non_idle:
        expr: avg by (instance) (1 - rate(node_cpu_seconds_total{mode="idle"}[5m]))
        detection_direction: above_expected
        min_rel_dev_from_expected: [0, 15]
  
  models:
    cpu_envelope:
      class: temporal_envelope
      queries: [cpu_non_idle]
      schedulers: [cpu_5m]
      seasonalities: [hod_smooth, dow_smooth]
  

  确切的调优参数取决于采样数据；最终模型规范始终会针对正在运行的 vmanomaly 实例进行验证。

在此对话过程中，助手使用了以下工具：

• vmanomaly_timeseries_characteristics，用于测量采样数据的特征
• vmanomaly_list_models 和 vmanomaly_get_model_schema，用于验证与 UI 兼容的模型
• vmanomaly_create_autotune_task 和 vmanomaly_get_autotune_task，用于调优共享参数
• vmanomaly_validate_model_config，用于验证调优后的模型
• vmanomaly_validate_config，用于验证配置

监控

在 HTTP 和 SSE 模式下，MCP 服务会在 /metrics 端点提供 Prometheus 格式的指标。

跟踪的操作：

• mcp_vmanomaly_initialize_total - 客户端连接数
• mcp_vmanomaly_call_tool_total{name,is_error} - 工具调用及成功/错误跟踪
• mcp_vmanomaly_read_resource_total - 文档资源读取次数
• mcp_vmanomaly_list_*_total - 列表操作（工具、资源、提示词）
• mcp_vmanomaly_error_total{method,error_class} - 按有限且不含敏感信息的类别统计错误

示例：

# Start in HTTP mode
VMANOMALY_ENDPOINT="http://localhost:8490" MCP_SERVER_MODE=http ./bin/mcp-vmanomaly

# Query metrics
curl http://localhost:8080/metrics

路线图

• 用于 MCP 服务监控的 Grafana 仪表板
• 添加 API 兼容性矩阵，以妥善处理 MCP 客户端与 vmanomaly 服务之间的版本差异（API 正在演进，部分功能可能不可用）

免责声明

此类 AI 服务和 Agent，以及 MCP 服务，均无法保证结果的准确性、完整性和可靠性。 你应仔细核查 AI 得出的结果。

MCP 服务及其响应的质量，很大程度上取决于客户端的能力和所使用模型的质量。

参与贡献

欢迎为 MCP vmanomaly 项目作出贡献！

欢迎提交问题、功能请求或拉取请求。

相关项目

• vmanomaly - VictoriaMetrics 异常检测
• VictoriaMetrics - 时间序列数据库
• mcp-victoriametrics - VictoriaMetrics 的 MCP 服务
• Model Context Protocol - MCP 规范

支持

有关 vmanomaly 的问题，请参阅 vmanomaly 文档。

有关 MCP 服务的问题，请在此仓库中提交 issue。