MCP Vmanomaly

🚀 vmanomaly的MCP服務器

這是為 vmanomaly（VictoriaMetrics的異常檢測應用程序）實現的 模型上下文協議（MCP） 服務器。它能與vmanomaly的REST API和 文檔 無縫集成，助力實現人工智能輔助的異常檢測、模型管理和可觀測性洞察。

🚀 快速開始

本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服務器通過環境變量進行配置：

模式

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服務器提供以下端點：

客戶端設置

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個工具）

模型配置（3個工具）

配置（1個工具）

文檔（1個工具）

兼容性（1個工具）

告警（1個工具）

對話示例

以下是一個示例對話，展示了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 - VictoriaMetrics異常檢測
• VictoriaMetrics - 時間序列數據庫
• mcp-victoriametrics - VictoriaMetrics的MCP服務器
• 模型上下文協議 - MCP規範

支持

有關vmanomaly的特定問題，請參閱 vmanomaly文檔。對於MCP服務器問題，請在本倉庫中提交問題。