ESXi Read-Only Diagnostics

---

なぜ？

vCenter を使わないスタンドアロンの ESXi があり、ERP の動作が遅く、ハードウェアに数千ドルを費やそうという話が出ています。 購入する前に、本当のボトルネックとなっているリソースを把握する必要があります。そのためには、Host Client では表示されない、または保存されないメトリクス（CPU Ready、Co-Stop、仮想ディスクごとのレイテンシ）を確認し、プロビジョニング済み容量と実際の容量を比較して、スナップショット、ログ、センサーを調べる必要があります。

この MCP を使えば、Claude に 「ERP の VM の動作が遅いのはなぜ？」 と尋ねるだけで、Claude がホストを照会し、データを照合して、数値を示しながら回答します。

本番環境にアクセスできる AI アシスタントを使うことになるため、サーバーには何かを変更する操作が一切ありません。シャットダウン、削除、作成、統合、再構成はできません。ESXi の読み取り専用ロールを持つユーザーと組み合わせれば、二重の保証になります。

✨ 何を尋ねられる？

「ホストを完全に診断して、ボトルネックが何か教えてください。」

「直近 1 時間で CPU Ready が最も高かった VM はどれですか？」

「各データストアで、各 VM が実際にどれだけの容量を使用していますか？」

「3 日以上前のスナップショットはありますか？」

「どの VM にも属さない大きなファイルがデータストアにありますか？」

「黄色または赤色のハードウェアセンサーはありますか？今週、ディスクエラーはありましたか？」

「CPU のオーバーコミットはありますか？物理コアあたりの vCPU 数はいくつですか？」

「RAM を増設するのとプロセッサーを交換するのでは、どちらがよいですか？」

🧰 ツール

ツール	返される情報
diagnostico_completo	以下のすべてを1回の呼び出しで取得します。最初の確認に最適です
host_info	メーカー、モデル、シリアル番号、BIOS、CPU（コア数／スレッド数／HT）、RAMの合計と使用量、ESXiのバージョンとビルド、稼働時間、電源ポリシー、ストレージコントローラー
salud_hardware	センサー（温度、ファン、電源、電圧）、メモリ、CPU、RAID／物理ディスクの状態（ホストにメーカーのCIMプロバイダーがある場合）。緑色以外の項目を先に表示します
config_host	ライセンス（キーはマスキング表示）と有効期限、NTPと実際の時計のずれ、SSH／Shell、稼働中のサービス、イメージプロファイル、syslog、リンク速度を含むネットワークカード、vSwitch、portgroup／VLAN、VMkernel
datastores	容量、使用量、空き容量、使用率、プロビジョニング率（シンプロビジョニングの過剰割り当て）、各データストアの背後にある物理ディスク、それを使用するVM
vms	VMごとの状態、vCPU、割り当て済み／アクティブ／消費RAM、バルーニング、スワップ、予約、上限、シェア、VMware Tools、ハートビート、時刻同期、NIC（e1000またはvmxnet3）、コントローラー、ディスク（シン／シック、実際の使用量）、ゲスト内の空き容量
snapshots	すべてのスナップショットの作成日、経過時間、実サイズ、およびN日を超えるもののマーク
performance	CPU %、CPU Ready %、Co-Stop %、CPUレイテンシー、アクティブメモリ、バルーニング、スワップ、仮想ディスクごとおよびデータストアごとのレイテンシー、IOPS。発生時刻とともに平均、p95、最大値を返します
historial_perf	数週間分の同じメトリクスを返します。営業時間で絞り込めます（パフォーマンス履歴を参照）
eventos	エラー、警告、アラーム、タスク、ログイン失敗を、ESXiの時計のずれを補正した時刻とともに表示します
top_archivos	各データストア内の最大ファイル、それらが属するVM、および孤立している可能性のあるファイル（登録済みVMのないvmdk）
overcommit	起動中のvCPUと物理スレッドの比較、割り当て済みRAMと物理RAMの比較、最大のVM
verificar_permisos	接続に使用しているユーザーと、そのユーザーがESXiへの書き込み権限を持っているかどうか

すべての応答には参照値（例：CPU Ready > 10 % = 競合）が含まれるため、アシスタントは推測せずに解釈できます。

🔒 セキュリティ：読み取り専用の仕組み

1. コード上での保証。 サーバーはプロパティの読み取りのみを行い、以下のvSphere APIメソッドを呼び出します。いずれも照会専用です。

メソッド	用途
CreateContainerView / Destroy	オブジェクトの一覧表示に使用する、セッション内の一時的なビュー
PerformanceManager.QueryPerf など	パフォーマンスメトリクス
HostDatastoreBrowser.SearchDatastoreSubFolders_Task	データストア内のファイルの一覧表示
EventManager.QueryEvents / CreateCollectorForEvents	イベントの読み取り（コレクターはセッションに属し、終了時に破棄されます）
AuthorizationManager.HasPrivilegeOnEntity / RetrieveEntityPermissions	ユーザー自身の権限の確認
OptionManager.QueryOptions、HostImageConfigManager.*Get*	オプションとイメージプロファイルの読み取り

何かを変更するMCPツールはなく、サーバーはそのようなツールが存在しないことをアシスタントに伝えます。

2. ESXi上での保証。 専用の読み取り専用ロールを持つユーザーを使用してください（インストールの手順1）。何かが書き込みを試みても、ESXiが拒否します。verificar_permisosで適切に設定されていることを確認できます。

{ "usuario": "mcp-readonly", "roles": ["ReadOnly+Browse"],
  "privilegios_escritura_detectados": [], "solo_lectura_garantizado_por_ESXi": true }

3. 認証情報。 パスワードが設定ファイルに保存されることはありません。keyringを使い、オペレーティングシステムの認証情報ストア（Windows資格情報マネージャー、macOSのKeychain、LinuxのSecret Service）に保存されます。ライセンスキーはマスキング表示されます。

🚀 インストール

要件

• uv（Python と依存関係を管理します）
• ESXi のポート 443 へのネットワークアクセス
• MCP クライアント：Claude Code、Claude Desktop など

1. ESXi で読み取り専用ユーザーを作成する

Host Client（https://<ip-esxi>/ui）で：

1. Manage → Security & users → Roles → Add role — 名前を ReadOnly+Browse にします：
   • ✅ System（Anonymous、Read、View）
   • ✅ Datastore → Browse datastore — これだけを選択します。Delete、FileManagement、AllocateSpace は選択しません
2. Manage → Security & users → Users → Add user — 例：mcp-readonly。 Enable shell access はオフのままにします。
3. Host → Actions → Permissions → Add user — mcp-readonly、ロール ReadOnly+Browse を選択し、 Propagate to all children にチェックを入れます。

Browse datastore がなくても MCP は動作しますが、top_archivos に表示されるのは登録済み VM のファイルだけになり （ISO や孤立したファイルは表示されません）、シンディスクの「使用済み」容量は概算になります。

2. パスワードをシステムの資格情報ストアに保存する

uvx esxi-readonly-mcp --set-password

ESXi のユーザー名とパスワードの入力を求められます（パスワードは表示されません）。入力した情報はシステムの資格情報ストアに保存されます。 何もクローンする必要はありません。uvx が PyPI からパッケージをダウンロードして実行します。

3. MCP クライアントにサーバーを登録する

Claude Code

claude mcp add esxi-readonly --scope user \
  -e ESXI_HOST=192.0.2.10 -e ESXI_USER=mcp-readonly \
  -- uvx esxi-readonly-mcp

Claude Desktop などのクライアント（claude_desktop_config.json または同等のファイル）：

{
  "mcpServers": {
    "esxi-readonly": {
      "command": "uvx",
      "args": ["esxi-readonly-mcp"],
      "env": { "ESXI_HOST": "192.0.2.10", "ESXI_USER": "mcp-readonly" }
    }
  }
}

Windows でクライアントが PATH から uvx を見つけられない場合は、uvx.exe のフルパスを指定します （例：C:\\Users\\<usuario>\\.local\\bin\\uvx.exe）。

クライアントを再起動し、*「ESXi MCP の権限を確認して」*と依頼します。

ソースコードから実行する場合

git clone https://github.com/nicolasboattini/esxi-readonly-mcp.git
cd esxi-readonly-mcp
uv sync
uv run esxi-readonly-mcp --set-password

MCP クライアントでは、コマンドとして uv run --directory /ruta/a/esxi-readonly-mcp esxi-readonly-mcp を使用します。

MCP クライアントを使わずにテストする

ESXI_HOST=192.0.2.10 ESXI_USER=mcp-readonly uv run python -c "from esxi_readonly_mcp import server; import json; print(json.dumps(server._host_info(), indent=2))"

（PowerShell の場合：$env:ESXI_HOST="192.0.2.10"; $env:ESXI_USER="mcp-readonly"; uv run python -c "..."）

⚙️ 設定

変数	必須	デフォルト	説明
ESXI_HOST	✅	—	ESXi（または vCenter）の IP アドレスまたは名前
ESXI_USER	✅	—	読み取り専用ユーザー
ESXI_PASSWORD		—	keyring を使用できない場合のみ（設定に平文で保存されるため、使用は避けてください）
ESXI_PORT		443	API のポート
ESXI_VERIFY_SSL		0	証明書を検証する場合は 1（デフォルトでは ESXi の自己署名証明書を受け入れます）
ESXI_PERF_DB		~/.esxi-readonly-mcp/perf_historial.db	パフォーマンス履歴用 SQLite データベースのパス

📈 パフォーマンス履歴

vCenter なしの ESXi では、メトリクスは直近 1 時間分のみ保存されます（20 秒間隔のサンプル）。過去数週間の業務時間帯における実際のピークを確認できるよう、サーバーにはこの 1 時間分のデータをローカルの SQLite データベースに保存する収集モードが用意されています。

uvx esxi-readonly-mcp --collect

これを毎時実行するようスケジュールし、Claude に、たとえば *「過去 4 週間の業務時間帯におけるパフォーマンス履歴を表示して」*と依頼します（historial_perf(dias=28, solo_horario_laboral=True)）。

Windows（タスク スケジューラ）

[Environment]::SetEnvironmentVariable("ESXI_HOST", "192.0.2.10", "User")
[Environment]::SetEnvironmentVariable("ESXI_USER", "mcp-readonly", "User")

$uvx = (Get-Command uvx).Source
$a  = New-ScheduledTaskAction -Execute $uvx -Argument 'esxi-readonly-mcp --collect'
$t  = New-ScheduledTaskTrigger -Daily -At 7:05am
$t.Repetition = (New-ScheduledTaskTrigger -Once -At 7:05am -RepetitionInterval (New-TimeSpan -Hours 1) -RepetitionDuration (New-TimeSpan -Hours 13)).Repetition
Register-ScheduledTask -TaskName "ESXi perf collect" -Action $a -Trigger $t -User $env:USERNAME

Linux / macOS（cron）

5 7-20 * * 1-5  ESXI_HOST=192.0.2.10 ESXI_USER=mcp-readonly $HOME/.local/bin/uvx esxi-readonly-mcp --collect

データベースには VM の名前とメトリクスが含まれます。デフォルトではユーザーフォルダー内に保存され、リポジトリの外に置かれます。

🧪 互換性

	状態
ESXi 6.7 U3 standalone	✅ 本番環境でテスト済み
ESXi 7.x / 8.x standalone	動作するはずです（同じ API を使用）。問題があれば報告してください
vCenter	コードではサポートされています（QueryEvents と過去の時間間隔を使用）。十分なテストは行われていません
pyVmomi 9.x + mcp 1.x	✅ テスト済み（mcp 2.x で API が変更されたため、プロジェクトでは mcp<2 に固定しています）

⚠️ 既知の制限事項

• 過去のメトリクス： vCenter がない場合、performance で確認できるのは約 1 時間分のみです。--collect と historial_perf を使用してください。
• イベント： スタンドアロンの ESXi には、直近約 1000 件のイベントが保存されます。監視システムが頻繁にセッションを開始する場合（たとえば、Zabbix の設定に問題がある場合）、数時間分しか残らないことがあります。
• RAID と物理ディスク： salud_hardware で確認できるのは、ESXi にメーカー（Dell、HPE、Lenovo）の CIM プロバイダーがある場合のみです。ない場合は、iDRAC / iLO / XCC で確認してください。
• VIB / ドライバーの一覧： Host.Config.Image が必要です。この権限ではイメージの変更も可能ですが、MCP では要求しません。代替手段として、SSH で esxcli software vib list を実行してください。
• ゲスト内の情報： MCP で確認できるのは VMware Tools が報告する情報（ドライブ、空き容量、IP）ですが、VM 内のファイルやプロセスは確認できません。

🛠️ トラブルシューティング

症状	推定される原因
No hay password...	uvx esxi-readonly-mcp --set-password が未実行です
vim.fault.InvalidLogin	ユーザー名またはパスワードが間違っているか、ユーザーにホスト上の権限が割り当てられていません
top_archivos で NoPermission が表示される	ロールに Datastore → Browse datastore がありません
intervalo="semana" で performance にデータがない	vCenter のない ESXi では正常です。realtime または historial_perf を使用してください
No module named 'mcp.server.fastmcp'	mcp 2.x を手動でインストールしています。uv sync は mcp<2 に従います
クライアントが uvx を見つけられない	command に uvx の絶対パスを指定してください
イベントの時刻がおかしい	ESXi の時計がずれています（NTP 未設定）。config_host にずれが表示され、eventos ではすでに補正されています

📁 構成

esxi-readonly-mcp/
├── src/esxi_readonly_mcp/
│   └── server.py    # servidor MCP + --collect + --set-password
├── pyproject.toml   # paquete PyPI (mcp<2, pyvmomi, keyring)
├── server.json      # ficha para el registro oficial de MCP
├── uv.lock
└── README.md

🤝 貢献

Issue とプルリクエストを歓迎します。特に、以下の貢献をお待ちしています。

• ESXi 7/8 と vCenter でのテスト
• 読み取り専用の新しいメトリクスやチェック

プロジェクトのルールはただひとつです。どのツールも環境を変更できてはなりません。 書き込み操作を追加する PR は、「オプション」であっても受け入れられません。

バージョンの公開（メンテナー向け）

1. pyproject.toml と server.json のバージョンを更新します（version と packages[0].version の 2 か所）。
2. コミットし、プッシュして、タグを付けます。

   git tag v0.1.1 && git push origin v0.1.1
   

3. ワークフロー release.yml でバージョンの一致を確認し、パッケージをビルドしてテストした後、PyPI と MCP の公式レジストリに公開します。トークンは不要です。GitHub の OIDC を使用します。

📄 ライセンス

MIT