vsphere-mcp

VMware vSphere / vCenter を AI コーディングツール（Claude Code、GitHub Copilot、Codex 等）から自然言語で操作するための MCP (Model Context Protocol) サーバーです。

注意: 開発・テストはすべて vcsim（vCenter Server Simulator）上で実施しています。商用 vSphere 環境への影響はありません。

機能一覧

情報取得ツール（28 個・読み取り専用・confirm 不要）

操作ツール（22 個・confirm 必須）

すべての操作ツールは confirm=True を指定しない限り実行されず、確認プロンプトを返します。

クイックスタート

前提条件

• Python 3.11 以上
• uv（推奨）
• Docker（vcsim を使ったローカル開発用）

1. vcsim の起動（開発用）

docker compose up -d

ポート 8989 で vCenter Server Simulator が起動し、データセンター・クラスター・ホスト・VM・データストアが事前作成されます。

2. インストール

# ソースから
git clone https://github.com/fukui-yuto/vsphere-mcp.git
cd vsphere-mcp
uv venv
uv pip install -e .

3. AI ツールへの登録

Claude Code

.claude/settings.json または .mcp.json に以下を追加します。

ローカル開発（vcsim）

{
  "mcpServers": {
    "vsphere-mcp": {
      "command": "uv",
      "args": ["run", "vsphere-mcp"],
      "env": {
        "VSPHERE_HOST": "localhost",
        "VSPHERE_PORT": "8989",
        "VSPHERE_USER": "user",
        "VSPHERE_PASSWORD": "pass",
        "VSPHERE_IGNORE_SSL": "true"
      }
    }
  }
}

本番 vCenter

{
  "mcpServers": {
    "vsphere-mcp": {
      "command": "uv",
      "args": ["run", "vsphere-mcp"],
      "env": {
        "VSPHERE_HOST": "vcenter.example.com",
        "VSPHERE_PORT": "443",
        "VSPHERE_USER": "administrator@vsphere.local",
        "VSPHERE_PASSWORD": "your-password"
      }
    }
  }
}

パスワードファイル（本番推奨）

{
  "mcpServers": {
    "vsphere-mcp": {
      "command": "uv",
      "args": ["run", "vsphere-mcp"],
      "env": {
        "VSPHERE_HOST": "vcenter.example.com",
        "VSPHERE_PORT": "443",
        "VSPHERE_USER": "administrator@vsphere.local",
        "VSPHERE_PASSWORD_FILE": "/run/secrets/vsphere_password"
      }
    }
  }
}

GitHub Copilot（VS Code）

プロジェクトルートに .vscode/mcp.json を作成します。

ローカル開発（vcsim）

{
  "servers": {
    "vsphere-mcp": {
      "command": "uv",
      "args": ["run", "vsphere-mcp"],
      "env": {
        "VSPHERE_HOST": "localhost",
        "VSPHERE_PORT": "8989",
        "VSPHERE_USER": "user",
        "VSPHERE_PASSWORD": "pass",
        "VSPHERE_IGNORE_SSL": "true"
      }
    }
  }
}

本番 vCenter

{
  "servers": {
    "vsphere-mcp": {
      "command": "uv",
      "args": ["run", "vsphere-mcp"],
      "env": {
        "VSPHERE_HOST": "vcenter.example.com",
        "VSPHERE_PORT": "443",
        "VSPHERE_USER": "administrator@vsphere.local",
        "VSPHERE_PASSWORD": "your-password"
      }
    }
  }
}

ヒント: VS Code のユーザー設定（settings.json）の mcp.servers に記述することも可能です。

OpenAI Codex CLI

プロジェクトルートに codex.json を作成します。

ローカル開発（vcsim）

{
  "mcpServers": {
    "vsphere-mcp": {
      "command": "uv",
      "args": ["run", "vsphere-mcp"],
      "env": {
        "VSPHERE_HOST": "localhost",
        "VSPHERE_PORT": "8989",
        "VSPHERE_USER": "user",
        "VSPHERE_PASSWORD": "pass",
        "VSPHERE_IGNORE_SSL": "true"
      }
    }
  }
}

本番 vCenter

{
  "mcpServers": {
    "vsphere-mcp": {
      "command": "uv",
      "args": ["run", "vsphere-mcp"],
      "env": {
        "VSPHERE_HOST": "vcenter.example.com",
        "VSPHERE_PORT": "443",
        "VSPHERE_USER": "administrator@vsphere.local",
        "VSPHERE_PASSWORD": "your-password"
      }
    }
  }
}

4. 利用例

登録後、自然言語で操作できます:

> クラスター内の全 VM を表示して

> VM "web-server-01" のステータスを確認して

> VM "dev-test-01" を起動して（confirm=True）

> 全データストアの空き容量を一覧表示して

> "db-server" のスナップショットを "before-upgrade" という名前で作成して

> "web-01" を "web-01-staging" としてクローンして

> "app-server" に 50GB のディスクを追加して

環境変数

SSL 設定

SSL 証明書の検証はデフォルトで有効です。自己署名証明書や開発環境の場合:

export VSPHERE_IGNORE_SSL=true

警告: 本番環境では SSL 検証を無効化しないでください。

安全設計

確認システム

すべての破壊的操作は 2 段階の確認パターンを使用します:

1. 1 回目の呼び出し（confirm=True なし）: 危険度付きのプレビューを返す
2. 2 回目の呼び出し（confirm=True あり）: 実際に操作を実行

# 1 回目 - 確認プロンプトを返す
power_off_vm(vm_name="web-01")
# -> {"status": "confirmation_required", "danger_level": "medium", ...}

# 2 回目 - 実行
power_off_vm(vm_name="web-01", confirm=True)
# -> {"status": "success", "vm_name": "web-01", "operation": "power_off"}

危険度レベル

ログ

すべての操作は構造化 JSON 形式でログ記録されます:

{"event": "power_off_vm", "vm_name": "web-01", "level": "info", "timestamp": "2025-05-04T12:00:00Z", "duration_ms": 1234.5}

認証情報はログに一切含まれません（自動マスク処理）。

エラーハンドリング

接続エラーは診断しやすいように型で分類されます:

クライアントは一時的な接続障害時に自動リトライします（最大 3 回、2 秒間隔）。

開発

テスト実行（vcsim が必要）

docker compose up -d
uv run pytest tests/ -v

リント・フォーマット

uv run ruff check src/ tests/
uv run ruff format src/ tests/

プロジェクト構成

vsphere-mcp/
  pyproject.toml
  docker-compose.yml              # vcsim 起動用
  src/vsphere_mcp/
    server.py                     # MCP サーバーエントリポイント
    config.py                     # 環境変数による設定管理
    client.py                     # vSphere 接続（遅延初期化・自動再接続）
    logging.py                    # 構造化ログ（パスワードマスク付き）
    metrics.py                    # Prometheus メトリクス（オプション）
    rbac.py                       # RBAC ポリシーエンジン
    i18n.py                       # 国際化メッセージフレームワーク（en/ja）
    py.typed                      # 型情報マーカー
    tools/
      _base.py                    # require_confirm / handle_tool_errors デコレータ
      inventory.py                # 情報取得ツール（15 個）
      power.py                    # 電源操作（4 個）
      snapshot.py                 # スナップショット管理（3 個）
      migration.py                # vMotion（1 個）
      lifecycle.py                # VM クローン/展開/削除（3 個）
      resources.py                # リソース変更: CPU/メモリ/ディスク/NIC（3 個）
      host.py                     # ホストメンテナンスモード（2 個）
      performance.py              # パフォーマンスメトリクス（2 個）
      events.py                   # イベント・アラーム（2 個）
      storage.py                  # ストレージ詳細（2 個）
      batch.py                    # 一括操作（2 個）
      guest.py                    # ゲスト OS 操作（2 個）
      tags.py                     # アノテーション・カスタム属性（3 個）
      advanced_settings.py        # 詳細設定（4 個）
    utils/
      property_collector.py       # PropertyCollector による効率的プロパティ取得
  tests/                          # vcsim 対象の統合テスト
  docs/
    ARCHITECTURE.md               # アーキテクチャ設計書
    DESIGN_DECISIONS.md           # 設計判断記録 (ADR)
    CONTRIBUTING.md               # コントリビュートガイド
    SECURITY.md                   # セキュリティポリシー
    CHANGELOG.md                  # 変更履歴
  .github/
    workflows/ci.yml              # GitHub Actions CI
    dependabot.yml                # Dependabot 設定（pip / GitHub Actions）

高度な機能

SSE トランスポート

複数クライアントから同一サーバーを共有する場合、SSE トランスポートを使用できます:

vsphere-mcp --transport sse --port 8080

Prometheus メトリクス

オプションの依存パッケージをインストールすることで、Prometheus 形式のメトリクスエンドポイントを公開できます:

pip install vsphere-mcp[metrics]
vsphere-mcp --metrics-port 9090

RBAC（ロールベースアクセス制御）

VSPHERE_RBAC_POLICY 環境変数にポリシー JSON ファイルのパスを指定することで、ツールごとのアクセス制御を設定できます:

export VSPHERE_RBAC_POLICY=/path/to/policy.json

国際化（i18n）

VSPHERE_LANG 環境変数でメッセージ言語を切り替えられます（デフォルト: en）:

export VSPHERE_LANG=ja

アーキテクチャ

Claude Code
    |  stdio（デフォルト）または HTTP/SSE
    v
vsphere-mcp サーバー（Python, FastMCP）
    |  pyVmomi（HTTPS）
    v
vCenter Server（本番）または vcsim（開発）

• トランスポート: stdio（デフォルト、ローカル運用に最適）または SSE（複数クライアント共有用）
• 接続: 初回ツール呼び出し時に遅延初期化、セッション切れ時に自動再接続
• プロパティ取得: PropertyCollector による効率的な一括クエリ
• 安全装置: require_confirm デコレータによる危険度別の確認システム
• エラーハンドリング: 型付き例外（VSphereAuthenticationError, VSphereSSLError, VSphereConnectionError）

既知の制限事項

• vcsim と実機の差異: vcsim と本番 vCenter で一部 API の挙動が異なります。詳細は vcsim ドキュメントを参照してください。
• ゲスト操作: shutdown_vm、reboot_vm、execute_guest_command、list_guest_processes はゲスト OS に VMware Tools がインストールされている必要があります。
• vMotion: 本番環境では互換性のあるホスト、共有ストレージ、適切なネットワーク構成が必要です。

ライセンス

Apache License 2.0

コントリビュート

開発環境のセットアップと貢献の手順は docs/CONTRIBUTING.md を参照してください。

セキュリティ

セキュリティポリシーと脆弱性の報告方法は docs/SECURITY.md を参照してください。

変更履歴

リリース履歴は docs/CHANGELOG.md を参照してください。

設計ドキュメント

• アーキテクチャ設計書
• 設計判断記録 (ADR)