MCP Vmanomaly

🚀 vmanomaly用MCPサーバー

vmanomaly（VictoriaMetricsの異常検知アプリケーション）用のModel Context Protocol (MCP)サーバーの実装です。

これにより、vmanomaly REST APIとドキュメントとのシームレスな統合が可能になり、AI支援による異常検知、モデル管理、およびオブザーバビリティの洞察を提供します。

✨ 主な機能

このMCPサーバーは、ClaudeなどのAIアシスタントがvmanomalyとやり取りできるようにします。

• ヘルスモニタリング：vmanomalyサーバーのヘルスステータスとビルド情報を確認します。
• モデル管理：異常検知モデルを一覧表示、検証、および構成します（10種類以上のモデルタイプ：zscore、prophet、mad、holtwinters、isolation_forestなど）。
• 構成生成：完全なvmanomaly YAML構成を生成します。
• アラートルール生成：異常スコアアラート用のVMAlertルールを生成します。
• ドキュメント検索：埋め込まれたvmanomalyドキュメント全体でファジーマッチングを使用した全文検索を行います。

MCPサーバーには最新のvmanomalyドキュメントが埋め込まれており、オンラインアクセスなしで検索できます。

MCPサーバーとその応答の品質は、クライアントの機能と使用するモデルの品質に大きく依存します。

📦 インストール

Go

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

バイナリ

Releasesページから最新のリリースをダウンロードし、PATHに配置してください。

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フラグは、Streamable HTTPモードを有効にするために使用されます。 サーバーモードの詳細については、構成セクションを参照してください。

利用可能なDockerイメージは、github registryを参照してください。 また、stdioモードのクライアントでMCPサーバーとDockerを使用する詳細については、バイナリの代わりにDockerを使用するセクションを参照してください。

ソースコード

ソースコードからバイナリをビルドするには、次の方法を使用できます。

• リポジトリをクローンします。

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

• クローンしたソースコードからバイナリをビルドします。

make build
# その後、バイナリmcp-vmanomalyを見つけることができ、このファイルをPATHにコピーするか、その場で実行できます。

• クローンしたソースコードからイメージをビルドします。

docker build -t mcp-vmanomaly .
# その後、dockerイメージmcp-vmanomalyを実行またはプッシュするために使用できます。

📚 ドキュメント

構成

vmanomaly用のMCPサーバーは、環境変数を介して構成されます。

モード

MCPサーバーは、次の動作モード（トランスポート）をサポートしています。

• stdio - 標準入出力モード。サーバーは標準入力からコマンドを読み取り、標準出力に応答を書き込みます。これはデフォルトモードで、ローカルサーバーに適しています。
• http - ストリーマブルHTTP。サーバーはHTTP接続用に/mcpエンドポイントを公開します。
• sse - Server-Sent Events。サーバーはSSE接続用に/sseおよび/messageエンドポイントを公開します。

⚠️ 重要提示

sseトランスポートモードは、MCP仕様(バージョン2025-03-26)から公式に廃止され、Streamable HTTPトランスポート（httpモード）に置き換えられました。 将来のリリースでは、そのサポートが廃止される可能性があります。クライアントがサポートしている場合は、Streamable HTTPトランスポートを使用してください。

トランスポートに関する詳細情報は、MCPドキュメントを参照してください。

• Core concepts → Transports
• Specifications → Transports

構成例

# 基本構成
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アシスタント → Model Context Protocol (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 - ホルト・ウィンターズの季節的方法
  • isolation_forest_univariate - 単変量時系列用のIsolation Forest
  • 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"
  

  この構成では、

  • 推論を1分ごとに実行します。
  • 過去2日間のデータを使用してモデルを1時間ごとに再トレーニングします。
  • 2.5の標準偏差の閾値を持つzスコアモデルを使用します。
  • すべてのインスタンスのCPU使用率をモニタリングします。

  この構成を検証するか、パラメータを調整しますか？

• あなた: 良さそう！テスト用の検知タスクを作成できますか？

• アシスタント: 最近のCPUデータで構成をテストするための異常検知タスクを作成します。

  タスクが正常に作成されました！ステータスは次のとおりです。

  • タスクID: task-abc-123
  • ステータス: 実行中
  • モデル: z_threshold=2.5のzscore
  • 時間範囲: 過去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ダッシュボードを追加する
• [ ] MCPクライアントとvmanomalyサーバーのバージョン差を適切に処理するためのAPI互換性マトリックスを追加する（APIは進化しており、機能が利用できない場合がある）

免責事項

このようなMCPサーバーを含むAIサービスとエージェントは、結果の正確性、完全性、および信頼性を保証することはできません。 AIで得られた結果を二重に確認する必要があります。

MCPサーバーとその応答の品質は、クライアントの機能と使用するモデルの品質に大きく依存します。

🤝 コントリビューション

MCP vmanomalyプロジェクトへのコントリビューションを歓迎します！ 問題の報告、機能リクエスト、またはプルリクエストを自由に送信してください。

関連プロジェクト

• vmanomaly - VictoriaMetricsの異常検知
• VictoriaMetrics - 時系列データベース
• mcp-victoriametrics - VictoriaMetrics用のMCPサーバー
• Model Context Protocol - MCP仕様

🆘 サポート

vmanomalyに関する質問は、vmanomalyドキュメントを参照してください。 MCPサーバーの問題は、このリポジトリに問題を開いてください。

📄 ライセンス

詳細はLICENSEを参照してください。