ZSvirt MCP Server

AI が ZSvirt の 2000+ API を動的に検索・呼び出しできるようにする MCP Server。

機能特性

• API 検索: キーワードで ZStack API を検索、あいまい一致に対応

• API 説明: API の詳細なパラメータ説明を取得

• API 実行: ZStack API を実行して結果を返す

• 監視メトリクス検索: 利用可能な監視メトリクスを検索

• 監視データ取得: 指定したメトリクスの監視データを取得

インストール

# 从 PyPI 安装
pip install zsvirt-mcp-server

# 或者使用 uv
uv pip install zsvirt-mcp-server

💡 インストールしなくても、uvx や pipx run でワンクリック実行も可能です（下記の使用方法を参照）

設定

以下の環境変数を設定します：

export ZSTACK_API_URL="http://localhost:8080"  # ZStack API 地址
export ZSTACK_ALLOW_ALL_API="false"             # 是否允许写操作（可选，默认 false）

# 认证方式一：用户名密码（会自动登录获取 Session）
export ZSTACK_ACCOUNT="admin"                   # 账户名
export ZSTACK_PASSWORD="your-password"          # 密码（明文）

# 认证方式二：直接传入 SessionID（优先级更高，设置后忽略用户名密码）
export ZSTACK_SESSION_ID="your-session-uuid"    # 已有的 Session UUID

# 查询响应控制（可选）
export ZSTACK_QUERY_DEFAULT_LIMIT="50"          # Query API 默认 limit（设 0 禁用）
export ZSTACK_RESPONSE_SIZE_LIMIT="65536"       # 响应大小上限，字节（设 0 禁用）

認証方式の説明

💡 ZSTACK_SESSION_ID とユーザー名・パスワードの両方が設定されている場合、Session ID が優先されます

セキュリティの説明

デフォルトでは、読み取り専用 API のみ呼び出し可能です。以下を含みます：

• Query* - クエリ系

• Get* - 取得系

• List* - リスト系

• Describe* - 説明系

• Check* - チェック系

• Count* - カウント系

• その他の読み取り専用操作...

書き込み操作 API（CreateVmInstance、DeleteVolume など）を呼び出す必要がある場合は、以下を設定します：

export ZSTACK_ALLOW_ALL_API="true"

⚠️ 警告: 書き込み操作を有効にすると、AI が作成・削除・変更などの危険な操作を実行できるようになります。慎重に使用してください！

クエリ応答の制御

Query API にはデフォルトで limit=50 が注入され、一度に全量のデータを取得してモデルのコンテキストウィンドウを圧迫するのを防ぎます。応答が 64KB を超えると inventories リストが自動的にトリミングされ、有効な JSON が返されることを保証します。

• 明示的に limit を渡した場合は上書きされません

• トリミングが発生した場合、応答には _truncation フィールドが含まれ、limit/start によるページングや fields による返却フィールドの絞り込みが案内されます

使用方法

MCP Server として実行

# 使用 uvx 直接运行（无需安装）
uvx zsvirt-mcp-server

# 或使用 pipx
pipx run zsvirt-mcp-server

# 如果已安装，直接运行
zsvirt-mcp-server

SSE モードで実行

デフォルトでは stdio トランスポートを使用します。SSE モードが必要な場合は、コマンドラインまたは環境変数で切り替えます：

# 命令行方式
uvx zsvirt-mcp-server --transport sse --host 0.0.0.0 --port 8000

# 环境变量方式
export MCP_TRANSPORT="sse"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"
export MCP_PATH="/sse"  # 可选
uvx zsvirt-mcp-server

説明: FASTMCP_HOST / FASTMCP_PORT / FASTMCP_MOUNT_PATH（FastMCP ネイティブ環境変数）にも対応しています

Streamable HTTP モードで実行

# 命令行方式
uvx zsvirt-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --streamable-path /mcp

# 环境变量方式
export MCP_TRANSPORT="streamable-http"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"
export MCP_STREAMABLE_PATH="/mcp"  # 可选
uvx zsvirt-mcp-server

説明: FASTMCP_STREAMABLE_HTTP_PATH にも対応しています

HTTP ヘッダー認証（マルチテナントモード）

SSE または streamable-http モードでは、管理者が共有の MCP Server を起動し、複数のユーザーが HTTP ヘッダーで各自の認証情報を渡すことで、マルチテナント分離を実現できます。

対応する HTTP ヘッダー：

認証情報の優先順位：HTTP ヘッダー > 環境変数

典型的な使用方法：

# 管理员启动共享 MCP Server
ZSTACK_ALLOW_ALL_API=false uvx zsvirt-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

ユーザーは MCP クライアント設定に HTTP ヘッダーを追加するだけで、各自のアカウントを使用できます：

{
  "mcpServers": {
    "zstack": {
      "transport": "streamable-http",
      "url": "http://mcp-server:8000/mcp",
      "headers": {
        "X-ZStack-Account": "user-a",
        "X-ZStack-Password": "password-a",
        "X-ZStack-API-URL": "http://zstack-env-1:8080"
      }
    }
  }
}

特性：

• 同じアカウントの Session は自動的にキャッシュされ再利用されるため、リクエストごとに新しい Session が作成されることはありません

• 異なる X-ZStack-API-URL のリクエストは異なる ZStack 環境にルーティングされます

• stdio モードでは HTTP ヘッダーがないため、自動的に環境変数認証にフォールバックし、動作は変わりません

Claude Desktop での設定

claude_desktop_config.json に以下を追加します：

方法1：ユーザー名・パスワードを使用

{
  "mcpServers": {
    "zstack": {
      "command": "uvx",
      "args": ["zsvirt-mcp-server"],
      "env": {
        "ZSTACK_API_URL": "http://your-zstack-server:8080",
        "ZSTACK_ACCOUNT": "admin",
        "ZSTACK_PASSWORD": "your-password",
        "ZSTACK_ALLOW_ALL_API": "false"
      }
    }
  }
}

方法2：Session ID を使用

{
  "mcpServers": {
    "zstack": {
      "command": "uvx",
      "args": ["zsvirt-mcp-server"],
      "env": {
        "ZSTACK_API_URL": "http://your-zstack-server:8080",
        "ZSTACK_SESSION_ID": "your-session-uuid",
        "ZSTACK_ALLOW_ALL_API": "false"
      }
    }
  }
}

💡 ZSTACK_ALLOW_ALL_API を "true" に設定すると、書き込み操作（作成・削除・変更など）を有効にできます

利用可能なツール

1. search_api

キーワードで ZStack API を検索します。

パラメータ:

• keywords (list[str]): 検索キーワード（例: ["Query", "Vm"]）

• category (str, オプション): カテゴリでフィルタリング

• limit (int, デフォルト 15): 最大返却数

2. describe_api

指定した API の詳細なパラメータ説明を取得します。

パラメータ:

• api_name (str): API 名（例: "QueryVmInstance"）

3. execute_api

ZStack API を実行します。

パラメータ:

• api_name (str): API 名

• parameters (dict): API パラメータ

4. search_metric

利用可能な監視メトリクスを検索します。

パラメータ:

• keywords (list[str]): 検索キーワード

• namespace (str, オプション): 名前空間でフィルタリング（あいまい一致に対応。例: vm/host）

• limit (int, デフォルト 20): 最大返却数

• match_mode (str, デフォルト or): キーワードの一致モード（and/or）

• prefer_namespaces (list[str], オプション): 優先的にソートされる名前空間リスト（デフォルト ["ZStack/VM","ZStack/Host"]）

💡 ヒント: namespace が不明な場合は最初に指定しなくても、返却結果に namespace 値が含まれるので選択できます 💡 デフォルトは match_mode=or（複数キーワードの和集合）。積集合が必要な場合は明示的に and を渡してください 💡 メトリクス名は namespace によって重複する場合があるため、namespace または prefer_namespaces を指定してソート優先度を確保することをお勧めします

5. get_metric_data

監視データを取得します。

パラメータ:

• namespace (str): 名前空間

• metric_name (str): メトリクス名

• start_time (str|int, オプション): 開始時間（ISO または秒単位のタイムスタンプ）

• end_time (str|int, オプション): 終了時間（ISO または秒単位のタイムスタンプ）

• period (int, デフォルト 60): サンプリング周期（秒）

• labels (list[str]|dict, オプション): ラベルフィルター（例: ["VMUuid=xxx"] または {"VMUuid":"xxx"}）

• summary_only (bool, オプション): 統計情報のみ返す（点数/最大/最小/平均/分散/標準偏差）

データ量のヒント:

• 返却点数のおおよその見積もり：ceil((end_time - start_time) / period) * series_count

• series_count は異なるラベル組み合わせの数。labels を指定しない場合、複数の系列が返される可能性があります

• 時間範囲を短くする、period を大きくする、labels フィルターを追加するなどして、出力が大きくなりすぎるのを防ぐことをお勧めします

6. get_metric_summary

監視メトリクスの集計 TopN を取得します（label_key でグループ化）。

パラメータ:

• namespace (str): 名前空間

• metric_name (str): メトリクス名

• label_key (str): ラベルキー（例: VMUuid/HostUuid）

• metric_names (list[str], オプション): 複数メトリクスの結合（例: in/out）

• start_time (str|int, オプション): 開始時間（ISO または秒単位のタイムスタンプ）

• end_time (str|int, オプション): 終了時間（ISO または秒単位のタイムスタンプ）

• period (int, デフォルト 60): サンプリング周期（秒）

• aggregate (str, デフォルト max): 単一メトリクスの集計方法 (max/avg/sum/min)

• combine (str, デフォルト sum): 複数メトリクスの結合方法 (sum/avg/max/min)

• threshold_op (str, オプション): しきい値の比較演算子 (>,>=,<,<=,==,!=)

• threshold_value (number, オプション): しきい値

• top_n (int, デフォルト 10): 返却件数

• resolve_resource (str, オプション): vm または host。名前の解決に使用

Query API 条件構文

Query 系 API では、conditions パラメータが以下の演算子をサポートします：

conditions の形式:

{
    "conditions": [
        {"name": "uuid", "op": "=", "value": "xxx"},
        {"name": "state", "op": "in", "value": "Running,Stopped"}
    ]
}

対話例

ユーザーの質問: 「UUID が ae6e57a0 で始まる VM の詳細を調べてください」

AI は以下の手順を実行します：

1. search_api(keywords=["Query", "Vm", "Instance"]) を呼び出す

2. describe_api(api_name="QueryVmInstance") を呼び出す

3. execute_api(api_name="QueryVmInstance", parameters={"conditions": [{"name": "uuid", "op": "?=", "value": "ae6e57a0%"}]}) を呼び出す

開発

# 克隆仓库
git clone https://github.com/ZSvirt/zsvirt-mcp-server/zsvirt-mcp-server.git
cd zsvirt-mcp-server

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

License

MIT