shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp-vmanomaly

这是一个为VictoriaMetrics异常检测工具vmanomaly实现的MCP服务器，允许AI助手通过协议直接与vmanomaly REST API交互，实现健康检查、模型管理、配置生成和文档搜索等功能。

article

README

🚀 vmanomaly的MCP服务器

这是为 vmanomaly（VictoriaMetrics的异常检测应用程序）实现的 模型上下文协议（MCP） 服务器。它能与vmanomaly的REST API和 文档 无缝集成，助力实现人工智能辅助的异常检测、模型管理和可观测性洞察。

Latest Release License Slack X

🚀 快速开始

本MCP服务器允许Claude等人工智能助手与vmanomaly进行交互，实现以下功能：

  • 健康监控：检查vmanomaly服务器的健康状况和构建信息。
  • 模型管理：列出、验证和配置异常检测模型（支持10多种模型类型，如zscore、prophet、mad、holtwinters、isolation_forest等）。
  • 配置生成：生成完整的vmanomaly YAML配置。
  • 告警规则生成：生成用于异常分数告警的VMAlert规则。
  • 文档搜索：对嵌入的vmanomaly文档进行全文模糊匹配搜索。

本MCP服务器包含最新的vmanomaly文档，无需联网即可进行搜索。不过，MCP服务器及其响应的质量很大程度上取决于客户端的能力和所使用模型的质量。

✨ 主要特性

  • 支持与Claude等AI助手交互，实现多种功能。
  • 内置最新的vmanomaly文档，支持离线搜索。

📦 安装指南

Go

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

二进制文件

从 发布页面 下载最新版本，并将其添加到系统路径中。

以下是Linux x86_64系统的示例（其他架构和平台也支持）：

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

可以使用Docker运行vmanomaly MCP服务器，这是一种无需安装Go或从源代码构建的简单启动方式。

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

请将环境变量替换为自己的参数。注意，MCP_SERVER_MODE=http 标志用于启用可流式HTTP模式。有关服务器模式的更多详细信息，请参阅 配置 部分。

可在 GitHub仓库 中查看可用的Docker镜像。有关在stdio模式下将Docker与MCP服务器和客户端一起使用的更多详细信息，请参阅 使用Docker代替二进制文件 部分。

源代码

若要从源代码构建二进制文件，可按以下步骤操作：

  • 克隆仓库： 
    git clone https://github.com/VictoriaMetrics-Community/mcp-vmanomaly.git
cd mcp-vmanomaly
  • 从克隆的源代码构建二进制文件： 
    make build
# 之后可以找到二进制文件mcp-vmanomaly，并将其复制到系统路径中或直接运行
  • 从克隆的源代码构建镜像： 
    docker build -t mcp-vmanomaly .
# 之后可以使用mcp-vmanomaly Docker镜像进行运行或推送

📚 详细文档

配置

vmanomaly的MCP服务器通过环境变量进行配置： | 变量 | 描述 | 是否必需 | 默认值 | 允许的值 | | ---- | ---- | ---- | ---- | ---- | | VMANOMALY_ENDPOINT | vmanomaly服务器端点URL（例如，http://localhost:8490） | 是 | - | - | | VMANOMALY_BEARER_TOKEN | 用于与vmanomaly API进行身份验证的Bearer令牌 | 否 | - | - | | VMANOMALY_HEADERS | 请求的自定义HTTP头（逗号分隔的键值对，例如，X-Custom=value1,X-Auth=value2） | 否 | - | - | | MCP_SERVER_MODE | 服务器操作模式。详情请参阅 模式。 | 否 | stdio | stdio, http, sse | | MCP_LISTEN_ADDR | HTTP服务器监听地址 | 否 | localhost:8080 | - | | MCP_DISABLED_TOOLS | 要禁用的工具列表，用逗号分隔 | 否 | - | - | | MCP_DISABLE_RESOURCES | 禁用所有资源（文档搜索仍可继续工作） | 否 | false | false, true | | MCP_HEARTBEAT_INTERVAL | 可流式HTTP协议的心跳间隔（通过网络基础设施保持连接活跃） | 否 | 30s | - | | MCP_LOG_LEVEL | 日志级别：debug（详细）、info（默认）、warn 或 error | 否 | info | - | | MCP_LOG_FILE | 日志文件路径（空表示stderr） | 否 | stderr | - |

模式

MCP服务器支持以下操作模式（传输协议）：

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

⚠️ 重要提示

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

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

配置示例

# 基本配置
export VMANOMALY_ENDPOINT="http://localhost:8490"

# 带身份验证
export VMANOMALY_ENDPOINT="http://localhost:8490"
export VMANOMALY_BEARER_TOKEN="your-token"

# 带自定义头（例如，在反向代理之后）
export VMANOMALY_HEADERS="X-Custom-Header=value1,X-Another=value2"

# 服务器模式
export MCP_SERVER_MODE="http"
export MCP_LISTEN_ADDR="0.0.0.0:8080"

# 日志记录
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客户端） |

客户端设置

Cursor

转到：设置 → Cursor设置 → MCP → 添加新的全局MCP服务器，并将以下配置粘贴到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 文件中（可通过打开 设置 → 开发者 → 编辑配置 找到该文件）：

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

  • 打开 设置 → 工具 → AI助手 → 模型上下文协议（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"
      }
    }
  }
}

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-community/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提供按类别组织的工具：

健康与信息（3个工具）

| 工具 | 描述 | | ---- | ---- | | vmanomaly_health_check | 检查vmanomaly服务器的健康状态 | | vmanomaly_get_buildinfo | 获取构建信息（版本、构建时间、Go版本） | | vmanomaly_get_metrics | 以Prometheus格式获取vmanomaly服务器的指标 |

模型配置（3个工具）

| 工具 | 描述 | | ---- | ---- | | vmanomaly_list_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 |

对话示例

以下是一个示例对话，展示了AI助手如何帮助进行vmanomaly配置和异常检测：

  • 你：我想为CPU使用率设置异常检测。有哪些可用的模型？

  • 助手：我可以帮助你为CPU使用率设置异常检测。让我检查一下vmanomaly中可用的模型。

    你的vmanomaly实例支持以下异常检测模型：

    • zscore - 基于z分数（与均值的标准差）的统计模型
    • prophet - Facebook的具有季节性的时间序列Prophet模型
    • mad - 中位数绝对偏差模型
    • holtwinters - Holt-Winters季节性方法
    • isolation_forest_univariate - 单变量时间序列的隔离森林
    • rolling_quantile - 基于滚动分位数的检测
    • auto - 自动模型选择

    对于CPU使用率监控，我建议从 zscore 模型开始，因为它简单、快速，并且适用于具有稳定模式的指标。你需要我生成一个配置吗？

  • 你：是的，请为使用zscore模型监控CPU使用率生成一个配置。

  • 助手：我将为使用zscore模型监控CPU使用率生成一个完整的vmanomaly配置：

    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"

    此配置将：

    • 每分钟运行一次推理
    • 每小时使用最近2天的数据重新训练模型
    • 使用阈值为2.5个标准差的zscore模型
    • 监控所有实例的CPU使用率

    你需要我验证此配置或调整任何参数吗？

  • 你：看起来不错！你能创建一个检测任务来测试它吗？

  • 助手：我将创建一个异常检测任务，以测试你最近的CPU数据配置：

    任务已成功创建！以下是状态：

    • 任务ID：task-abc-123
    • 状态：运行中
    • 模型：zscore，z_threshold=2.5
    • 时间范围：最近24小时
    • 进度：正在处理数据...

    该任务正在分析你的CPU使用率数据。你可以通过查询异常分数指标在VictoriaMetrics中查看结果。你需要我检查任务状态或展示如何查询结果吗？

在这个对话中，助手使用了以下工具：

  • vmanomaly_list_models 来获取可用的模型类型
  • vmanomaly_validate_config 来验证配置
  • vmanomaly_create_detection_task 来启动异常检测
  • vmanomaly_search_docs 来提供有关模型参数的上下文

🔧 技术细节

监控

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

跟踪的操作：

  • mcp_vmanomaly_initialize_total - 客户端连接
  • mcp_vmanomaly_call_tool_total{name,is_error} - 带成功/错误跟踪的工具调用
  • mcp_vmanomaly_read_resource_total{uri} - 文档资源读取
  • mcp_vmanomaly_list_*_total - 列表操作（工具、资源、提示）
  • mcp_vmanomaly_error_total{method,error} - 按方法和类型分类的错误

示例：

# 以HTTP模式启动
VMANOMALY_ENDPOINT="http://localhost:8490" MCP_SERVER_MODE=http ./bin/mcp-vmanomaly

# 查询指标
curl http://localhost:8080/metrics

路线图

  • [ ] 为常见的vmanomaly工作流（模型选择、故障排除）添加提示
  • [ ] 为MCP服务器监控添加Grafana仪表盘
  • [ ] 添加API兼容性矩阵，以优雅地处理MCP客户端和vmanomaly服务器之间的版本差异（API正在发展，某些功能可能不可用）

📄 许可证

本项目遵循相关开源许可证，具体请查看仓库中的 LICENSE 文件。

免责声明

像这样的人工智能服务、代理以及MCP服务器不能保证结果的准确性、完整性和可靠性。你应该对通过人工智能获得的结果进行二次检查。MCP服务器及其响应的质量很大程度上取决于客户端的能力和所使用模型的质量。

贡献

欢迎对MCP vmanomaly项目做出贡献！请随时提交问题、功能请求或拉取请求。

相关项目

支持

有关vmanomaly的特定问题，请参阅 vmanomaly文档。对于MCP服务器问题，请在本仓库中提交问题。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端