ESXi Read-Only Diagnostics

---

为什么？

你有一台独立运行的 ESXi（没有 vCenter），ERP 运行缓慢，有人提议花几千美元购买硬件。 购买之前，你需要知道真正的瓶颈资源是什么。这意味着要查看 Host Client 隐藏或不保存的指标（CPU Ready、Co-Stop、虚拟磁盘延迟），对比预分配空间和实际空间，并检查快照、日志和传感器。

使用这个 MCP，你只需问 Claude “ERP 虚拟机为什么这么慢？”，它就会自行查询主机、交叉分析数据，并用具体数字给出答复。

而且，既然你要让 AI 助手访问生产基础设施，这个服务不会提供任何能修改内容的操作：它无法关闭、删除、创建、合并或重新配置任何东西。再配合一个拥有 ESXi 只读角色的用户，就有了双重保障。

✨ 你可以问它什么

“全面诊断这台主机，并告诉我瓶颈在哪里。”

“过去一小时里，哪台虚拟机的 CPU Ready 最高？”

“每台虚拟机在每个 datastore 中实际占用多少空间？”

“有没有超过 3 天的快照？”

“datastore 里有哪些不属于任何虚拟机的大文件？”

“有没有硬件传感器显示黄色或红色？这周出现过磁盘错误吗？”

“我的 CPU 是否超额分配？每个物理核心对应多少个 vCPU？”

“买更多 RAM 还是更换处理器更划算？”

🧰 工具

工具	返回内容
diagnostico_completo	一次调用返回以下所有内容——理想的起点
host_info	制造商、型号、序列号、BIOS、CPU（核心数 / 线程数 / HT）、RAM 总量和已用量、ESXi 版本和构建号、运行时间、电源策略、存储控制器
salud_hardware	传感器（温度、风扇、电源、 电压）、内存、CPU，以及主机安装了制造商 CIM 提供程序时的 RAID / 物理磁盘状态。优先列出状态非绿色的项目
config_host	许可证（密钥已屏蔽）和到期时间、NTP 和 实际时钟偏差、SSH / Shell、活动服务、映像配置文件、syslog、带链路速度的网卡、vSwitch、portgroup / VLAN、VMkernel
datastores	容量、已用、可用、使用率、预配百分比（thin 超额分配）、每个 datastore 对应的物理磁盘，以及使用它的 VM
vms	每个 VM 的状态、vCPU、已分配 / 活动 / 已消耗 RAM、气球内存、交换空间、预留、限制、shares、VMware Tools、心跳、时间同步、NIC（e1000 与 vmxnet3）、控制器、磁盘（thin / thick、实际用量）、guest 内部可用空间
snapshots	所有快照的日期、创建时长、实际大小，以及超过 N 天的快照标记
performance	CPU %、CPU Ready %、Co-Stop %、CPU 延迟、活动内存、气球内存、交换空间、虚拟磁盘和 datastore 的延迟、IOPS。返回平均值、p95 和最大值，以及发生时间
historial_perf	数周内的相同指标，可按工作时间筛选（参见性能历史记录）
eventos	错误、警告、警报、任务和登录失败，并根据 ESXi 时钟偏差校正时间
top_archivos	每个 datastore 中最大的文件、所属 VM，以及可能的孤立文件（没有已注册 VM 的 vmdk）
overcommit	已开机 vCPU 与物理线程数、已分配 RAM 与物理 RAM、最大的 VM
verificar_permisos	连接所用的用户，以及该用户是否拥有 ESXi 写入权限

所有响应都附带参考值（例如：CPU Ready > 10 % = 争用），以便助手无需猜测即可解读。

🔒 安全性：如何确保只读

1. 在代码中。 服务只读取属性，并调用以下 vSphere API 方法，且这些方法都只用于查询：

方法	用途
CreateContainerView / Destroy	当前会话的临时视图，用于列出对象
PerformanceManager.QueryPerf 和相关方法	性能指标
HostDatastoreBrowser.SearchDatastoreSubFolders_Task	列出 datastore 中的文件
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 只能看到已注册虚拟机的文件 （看不到 ISO 或孤立文件），而 thin 磁盘的“已用”空间也只是近似值。

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 只保存最近一小时的指标（每 20 秒采样一次）。若要查看过去几周工作时间内的实际峰值，服务提供了一个采集器模式，可将这一小时的数据保存到本地 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

数据库包含虚拟机名称和指标。默认情况下，它位于你的用户文件夹中，不属于任何代码仓库。

🧪 兼容性

	状态
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 和物理磁盘：**只有在 ESXi 安装了制造商（Dell、HPE、Lenovo）的 CIM 提供程序时，salud_hardware 才会显示这些信息。否则，请在 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
performance 在 intervalo="semana" 时没有数据	这在没有 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

🤝 参与贡献

欢迎提交 Issues 和 pull request，尤其是：

• 在 ESXi 7/8 和 vCenter 上进行测试
• 新增指标或只读检查

项目只有一条规则：**任何工具都不得修改环境。**即使是“可选”的写入操作，也不会接受相关 PR。

发布版本（维护者）

1. 更新 pyproject.toml 和 server.json 中的版本号（两处：version 和 packages[0].version）。
2. 提交 commit、推送并打标签：

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

3. 工作流 release.yml 会检查版本是否一致、构建并测试软件包，将其发布到 PyPI，然后发布到 MCP 官方注册表。无需令牌：使用 GitHub 的 OIDC。

📄 许可证

MIT