VMware Monitor

VMware Monitor

For a read-only check of this skill with your model and agent host, use the shared model-fit self-test in the marketplace root.

Author: Wei Zhou, VMware by Broadcom — [email protected] This is a community-driven project by a VMware engineer, not an official VMware product. For official VMware developer tools see developer.broadcom.com.

English | 中文

Read-only VMware vCenter/ESXi monitoring — 33 tools. No destructive operations exist in this codebase, and a test enforces that.

Why a separate repository? VMware Monitor is fully independent from VMware-AIops. No power off, delete, create, reconfigure, snapshot-create/revert/delete, clone, or migrate functions exist in this codebase — not a prompt constraint, an absence.

How that is enforced, precisely. tests/eval/regression/test_read_only_enforcement.py parses every source file with ast and requires each vSphere method the package calls to appear on a reviewed allowlist, cross-checked against pyVmomi's own type metadata: anything returning a vim.Task, or gated by vCenter on a non-read privilege, fails unless a human wrote down why. Today that allowlist is fourteen methods. The check is a gate on the code as written — it cannot see a method name assembled at runtime, and nothing runs it automatically, so it holds only as far as someone runs the test suite. For a guarantee that does not depend on this repository at all, point the skill at a dedicated account holding vCenter's built-in Read-Only role (which reads need more than that role).

What "read-only" does not cover. It is a claim about vCenter/ESXi: no code path changes their state. On vCenter the skill opens only its own login session and short-lived query handles it releases. It does write locally: ~/.vmware-monitor/config.yaml and .env (via init; plaintext passwords in .env are rewritten as b64: on load), audit logs (~/.vmware/audit.db for MCP calls, ~/.vmware-monitor/audit.log for CLI commands), --html snapshots in ~/vmware-health/, and — only after daemon start — daemon.pid, scan.log, and posts to a webhook you configured. Full table: setup guide.

[ClawHub] [Skills.sh] [Claude Code Marketplace] [License: MIT]

Companion Skills

Upgrading to 2.0

2.0 renames 23 of its MCP tools so every name starts with a verb (e.g. active_sessions → list_active_sessions, active_tasks → list_active_tasks, certificate_status → get_certificate_status). The full old → new table is in RELEASE_NOTES.md. Nothing else changes: same tools, parameters, safety gates and CLI commands. If an agent prompt, script or ~/.vmware/rules.yaml names a tool, update it — though deny rules written with the old names keep working with vmware-policy ≥ 1.18 (vmware-audit policy lists any rule the renames widened), and vmware-pilot ≥ 1.13 translates old names in saved workflows. If an install older than 2.0 shares that rules.yaml, give it vmware-policy ≥ 1.18.2 too: it matches each rule against both the old and the new name, so one file serves both.

⚡ Quick Investigation Reports

Five opinionated, read-only reports that answer an operator's real questions — each aggregates and correlates server-side and hands back a high-signal result (never raw inventory). Every report also renders a self-contained offline HTML snapshot with --html (no external assets, nothing leaves the machine; drill-down detail collapses in native <details> sections, zero JavaScript).

# Triage the estate, then drill into whatever it flags:vmware-monitor attention                         # what needs attention now, all vCentersvmware-monitor summary --top 5                   # is anything on fire, one vCentervmware-monitor investigate vm web-01 --hours 72  # everything around a VM, 72h event windowvmware-monitor investigate vm web-01 --html      # → offline snapshot in ~/vmware-health/

Unknown object names return a teaching error naming exactly how to list objects. Via MCP these are the tools get_cluster_health_summary, get_cross_vcenter_attention, investigate_vm, investigate_host, investigate_datastore — the model calls them and explains the aggregated result in operational language. Full flags: references/cli-reference.md.

MCP Apps cluster health view (unreleased)

get_cluster_health_summary also advertises ui://vmware-monitor/cluster-health.html to MCP Apps hosts. A supporting host can render a live cluster dashboard and use its Investigate buttons to call the read-only host or datastore tool through the same MCP server, role, Policy and audit path. The HTML is self-contained and renders vSphere names as text. Hosts without MCP Apps support receive the same tool result as before. The view and real vCenter data have been verified through the production loopback HTTP transport; visual rendering in a current third-party host remains to be verified. This is separate from the CLI's offline --html snapshot.

Quick Install (Recommended)

Works with Claude Code, Cursor, Codex, Gemini CLI, Trae, and 30+ AI agents:

# Via Skills.shnpx skills add vmware-skills/VMware-Monitor
# Via ClawHubclawhub install @zw008/vmware-monitor

PyPI Install (No GitHub Access Required)

# Install via uv (recommended)uv tool install vmware-monitor
# Or via pippip install vmware-monitor
# China mainland mirror (faster)pip install vmware-monitor -i https://pypi.tuna.tsinghua.edu.cn/simple

Offline / Air-Gapped Install (from source)

This project uses the modern PEP 517 build system (hatchling), so there is no setup.py by design — that is expected, not a missing file. If you cloned the source and hit ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build, your pip is older than 21.3 and cannot do an editable (-e) install with a non-setuptools backend. Editable mode is a developer convenience, not needed to run the tool — do one of:

# From the source tree — a normal (non-editable) install builds a wheel:pip install .              # NOT  pip install -e .
# ...or upgrade pip first, and editable works too:pip install --upgrade pip && pip install -e .

For a truly air-gapped host, build the wheels on a connected machine and copy them over — the target then needs no network:

# On a connected machine, collect this package + its dependencies as wheels:pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)
# Copy dist/ to the air-gapped host, then install offline:pip install --no-index --find-links dist vmware-monitor

Capabilities (Read-Only)

Architecture

User (Natural Language)  ↓AI CLI Tool (Claude Code / Gemini / Codex / Aider / Continue / Trae / Kimi)  ↓ Reads SKILL.md / AGENTS.md / rules  ↓vmware-monitor CLI (read-only)  ↓ pyVmomi (vSphere SOAP API)  ↓vCenter Server ──→ ESXi Clusters ──→ VMs    orESXi Standalone ──→ VMs

Version Compatibility

Official Broadcom References

• SDKs: https://developer.broadcom.com/sdks — VCF Python SDK (recommended for VCF 9+, bundles pyVmomi + vSAN SDK), vSphere Automation SDK for Python
• REST APIs: https://developer.broadcom.com/xapis — vSphere Automation API, VCF API
• CLI Tools: https://developer.broadcom.com/tools — PowerCLI 9.1, ESXCLI, OVF Tool

1. Inventory

2. Health & Monitoring

Monitored Event Types:

3. VM Info & Snapshot List (Read-Only)

4. Scheduled Scanning & Notifications

5. Safety Features

What's NOT Included (By Design)

These operations do not exist in this repository:

• ❌ Power on/off, reset, suspend VMs
• ❌ Create, delete, reconfigure VMs
• ❌ Create, revert, delete snapshots
• ❌ Clone or migrate VMs
• ❌ _double_confirm, _show_state_preview, _validate_vm_params

For these operations, use the full VMware-AIops repository.

Running with local or small models? See skills/vmware-monitor/references/agent-guardrails.md.

Common Workflows

Daily Health Check

1. Check alarms: vmware-monitor health alarms --target prod-vcenter
2. Review recent events: vmware-monitor health events --hours 24 --severity warning
3. List hosts: vmware-monitor inventory hosts — check connection state and memory usage

Investigate a Specific Object (drill-down)

One call correlates the object with its surrounding infrastructure and recent history — see ⚡ Quick Investigation Reports above.

1. Start from triage: vmware-monitor attention (all vCenters) or vmware-monitor summary (one)
2. Drill into what it flags: vmware-monitor investigate vm <name> (or host / datastore)
3. Widen the event window with --hours 72; share it with --html (offline snapshot)
4. If the name is unknown → the teaching error names how to list objects (inventory vms/hosts, list_all_datastores)

Set Up Continuous Monitoring

1. Configure webhook in ~/.vmware-monitor/config.yaml
2. Start daemon: vmware-monitor daemon start
3. Daemon scans every 15 min, sends alerts to Slack/Discord

Troubleshooting

Alarms returns empty but vCenter shows alarms

The get_alarms tool queries triggered alarms at the root folder level. Some alarms are entity-specific — try checking events instead: vmware-monitor health events --hours 1 --severity info.

"Connection refused" error

1. Run vmware-monitor doctor to diagnose
2. Verify target hostname/IP and port (443) in config.yaml
3. For self-signed certs: trust the CA; set verify_ssl: false only for an isolated lab host

Events returns too many results

Use severity filter: --severity warning (default) filters out info-level events. Use --hours 4 to narrow the time range.

VM info shows "guest_os: unknown"

VMware Tools not installed or not running in the guest. Install/start VMware Tools for guest OS detection, IP address, and guest family info.

Doctor passes but commands fail with timeout

vCenter may be under heavy load. Try targeting a specific ESXi host directly instead of vCenter, or increase connection timeout in config.yaml.

doctor reports "no vSphere role", or every command fails with "session is not authenticated"

The account logs in but has no vSphere role, so vCenter gives it no session (AIops#47). Assign it a role (Read-Only or higher) on the vCenter root folder: Administration > Access Control > Global Permissions. Changing the password will not help. vmware-monitor doctor reports this case by name, and attention counts such a target as unread (overall at least WARN).

Supported AI Platforms

Platform Comparison

MCP Server Integrations

The vmware-monitor MCP server works with any MCP-compatible agent or tool. Ready-to-use configuration templates are in examples/mcp-configs/. All 33 tools are read-only, enforced by the allowlist gate described above.

Xiaoguai (小怪) — a self-hostable, audit-first agent platform (Rust, single binary + embedded SQLite) from the same maintainer. It runs the read-only vmware-monitor MCP server as one of its toolboxes; being both an MCP consumer and an MCP server, its HMAC-chained audit log pairs naturally with this skill's read-only design — every query is logged, and no code path here mutates. See its MCP integration guide.

Fully local operation (no cloud API required):

# Aider + Ollama + vmware-monitor (via SKILL.md)aider --conventions skills/vmware-monitor/SKILL.md --model ollama/qwen2.5-coder:32b
# Any MCP agent + local model + vmware-monitor MCP server# See examples/mcp-configs/ for your agent's config format

Installation

Step 0: Prerequisites

# Python 3.10+ requiredpython3 --version
# Node.js 18+ required for Gemini CLI and Codex CLInode --version

Step 1: Clone & Install Python Backend

git clone https://github.com/vmware-skills/VMware-Monitor.gitcd VMware-Monitorpython3 -m venv .venvsource .venv/bin/activatepip install -e .

Step 2: Configure

mkdir -p ~/.vmware-monitorcp config.example.yaml ~/.vmware-monitor/config.yaml# Edit config.yaml with your vCenter/ESXi targets

Set passwords via .env file (recommended):

cp .env.example ~/.vmware-monitor/.envchmod 600 ~/.vmware-monitor/.env# Edit and fill in your passwords

Security note: Prefer .env file over command-line export to avoid passwords appearing in shell history. config.yaml stores only hostnames, ports, and a reference to the .env file — it does not contain passwords or tokens. All secrets are stored exclusively in .env (chmod 600). Webhook notifications are disabled by default; when enabled, payloads go to user-configured URLs only and carry no credentials from your config — but they do carry vSphere's own alarm, event, and log text, which can include host names, IPs, and user names. We recommend a dedicated service account with vCenter's built-in Read-Only role.

Password environment variable naming convention:

VMWARE_{TARGET_NAME_UPPER}_PASSWORD# Replace hyphens with underscores, UPPERCASE# Example: target "home-esxi" → VMWARE_HOME_ESXI_PASSWORD# Example: target "prod-vcenter" → VMWARE_PROD_VCENTER_PASSWORD

Step 3: Connect Your AI Tool

Choose one (or more) of the following:

Option A: Claude Code

Method 1: Skills.sh or ClawHub (recommended)

Either installer places the skill in Claude Code's skills directory for you:

npx skills add vmware-skills/VMware-Monitor# orclawhub install @zw008/vmware-monitor

Method 2: Manual skill install

git clone https://github.com/vmware-skills/VMware-Monitor.gitcd VMware-Monitor
# Copy the skill into Claude Code's personal skills directorymkdir -p ~/.claude/skills/vmware-monitorcp -r skills/vmware-monitor/. ~/.claude/skills/vmware-monitor/

For tool access (not just skill context), also register the MCP server:

claude mcp add vmware-monitor -- vmware-monitor mcp

Restart Claude Code, then:

> Show me all VMs on esxi-lab.example.com

Option B: Gemini CLI

# Install Gemini CLInpm install -g @google/gemini-cli
# Load the skill as project context (Gemini CLI reads GEMINI.md on startup)cp skills/vmware-monitor/SKILL.md ./GEMINI.md

For tool access (not just context), register the MCP server in ~/.gemini/settings.json:

{  "mcpServers": {    "vmware-monitor": {      "command": "vmware-monitor",      "args": ["mcp"],      "env": { "VMWARE_MONITOR_CONFIG": "~/.vmware-monitor/config.yaml" }    }  }}

Then start Gemini CLI:

gemini> Show me all VMs on my ESXi host

Option C: OpenAI Codex CLI

# Install Codex CLInpm i -g @openai/codex# Or on macOS:# brew install --cask codex
# Copy skill to Codex skills directorymkdir -p ~/.codex/skills/vmware-monitorcp skills/vmware-monitor/SKILL.md ~/.codex/skills/vmware-monitor/SKILL.md
# Copy AGENTS.md to project rootcp skills/vmware-monitor/SKILL.md ./AGENTS.md

Then start Codex CLI:

codex --enable skills> List all VMs on my ESXi

Option D: Aider (supports local models)

# Install Aiderpip install aider-chat
# Install Ollama for local models (optional)# macOS:brew install ollamaollama pull qwen2.5-coder:32b
# Run with cloud APIaider --conventions skills/vmware-monitor/SKILL.md
# Or with local model via Ollamaaider --conventions skills/vmware-monitor/SKILL.md \  --model ollama/qwen2.5-coder:32b

Option E: Continue CLI (supports local models)

# Install Continue CLInpm i -g @continuedev/cli
# Copy rules filemkdir -p .continue/rulescp skills/vmware-monitor/SKILL.md .continue/rules/vmware-monitor.md

Configure ~/.continue/config.yaml for local model:

models:  - name: local-coder    provider: ollama    model: qwen2.5-coder:32b

Then:

cn> Check ESXi health and alarms

Option F: Trae IDE

Copy the rules file to your project's .trae/rules/ directory:

mkdir -p .trae/rulescp skills/vmware-monitor/SKILL.md .trae/rules/project_rules.md

Trae IDE's Builder Mode reads .trae/rules/ Markdown files at startup.

Note: You can also install Claude Code extension in Trae IDE and use .claude/skills/ format directly.

Option G: Kimi Code CLI

# Copy skill file to Kimi skills directorymkdir -p ~/.kimi/skills/vmware-monitorcp skills/vmware-monitor/SKILL.md ~/.kimi/skills/vmware-monitor/SKILL.md

Option H: MCP Server (Glama / Claude Desktop)

The MCP server exposes VMware read-only monitoring as tools via the Model Context Protocol. Works with any MCP-compatible client (Claude Desktop, Cursor, etc.).

After uv tool install vmware-monitor, start the MCP server with one command (v1.5.15+):

# Recommended — single command, no network re-resolvevmware-monitor mcp
# With a custom config pathVMWARE_MONITOR_CONFIG=/path/to/config.yaml vmware-monitor mcp

Claude Desktop config (claude_desktop_config.json):

{  "mcpServers": {    "vmware-monitor": {      "command": "vmware-monitor",      "args": ["mcp"],      "env": {        "VMWARE_MONITOR_CONFIG": "/path/to/config.yaml"      }    }  }}

# Run without installing (requires PyPI access each launch)uvx --from vmware-monitor vmware-monitor mcp
# Legacy entry point (still works, kept for backward compatibility)vmware-monitor-mcp

Option I: Standalone CLI (no AI)

# Already installed in Step 1source .venv/bin/activate
vmware-monitor inventory vms --target home-esxivmware-monitor health alarms --target home-esxivmware-monitor vm info my-vm --target home-esxi

Update / Upgrade

Already installed? Re-run the install command for your channel to get the latest version:

Check your current version: vmware-monitor --version

Chinese Cloud Models

For users in China who prefer domestic cloud APIs or have limited access to overseas services.

DeepSeek

export DEEPSEEK_API_KEY="your-key"aider --conventions skills/vmware-monitor/SKILL.md \  --model deepseek/deepseek-coder

Qwen (Alibaba Cloud)

export DASHSCOPE_API_KEY="your-key"aider --conventions skills/vmware-monitor/SKILL.md \  --model qwen/qwen-coder-plus

Local Models (Aider + Ollama)

For fully offline operation — no cloud API, no internet, full privacy.

brew install ollamaollama pull qwen2.5-coder:32bollama serve
aider --conventions skills/vmware-monitor/SKILL.md \  --model ollama/qwen2.5-coder:32b

CLI Reference

# Diagnosticsvmware-monitor doctor                   # Check environment, config, connectivityvmware-monitor doctor --skip-auth       # Skip vSphere auth check (faster)vmware-monitor access-info [--tool <mcp-tool>] [--target <name>]  # Account in use + privileges per tool
# MCP Config Generatorvmware-monitor mcp-config generate --agent goose        # Generate config for Goosevmware-monitor mcp-config generate --agent claude-code  # Generate config for Claude Codevmware-monitor mcp-config list                          # List all supported agents
# Inventoryvmware-monitor inventory vms [--target <name>]vmware-monitor inventory vms --limit 10 --sort-by memory_mb   # Top 10 VMs by memoryvmware-monitor inventory vms --power-state poweredOn           # Only powered-on VMsvmware-monitor inventory vms --sort-by folder_path             # Group VMs by inventory folder# All `inventory vms` results include a `folder_path` field (e.g. `/Datacenters/Production/Web Tier`).# MCP tool `list_virtual_machines` additionally supports `folder_filter="Production"` for case-insensitive folder-tree search.vmware-monitor inventory hosts [--target <name>]vmware-monitor inventory datastores [--target <name>]vmware-monitor inventory clusters [--target <name>]
# Healthvmware-monitor health alarms [--target <name>]vmware-monitor health events [--hours 24] [--severity warning]
# VM Info (read-only)vmware-monitor vm info <vm-name>vmware-monitor vm snapshot-list <vm-name>
# Scanning & Daemonvmware-monitor scan now [--target <name>]vmware-monitor daemon startvmware-monitor daemon stopvmware-monitor daemon status

Configuration

See config.example.yaml for all options.

Project Structure

VMware-Monitor/├── skills/                        # Skills index (npx skills add)│   └── vmware-monitor/│       ├── SKILL.md│       └── references/            # Detailed docs loaded on-demand├── vmware_monitor/                # Python backend (read-only only)│   ├── config.py                  # YAML + .env config│   ├── connection.py              # Multi-target pyVmomi│   ├── cli.py                     # Typer CLI (read-only commands only)│   ├── ops/│   │   ├── inventory.py           # VMs, hosts, datastores, clusters│   │   ├── health.py              # Alarms, events, sensors│   │   └── vm_info.py                 # VM info, snapshot list (read-only)│   ├── scanner/                   # Log scanning daemon│   ├── notify/                    # Notifications (JSONL + webhook)│   └── mcp_server/                # MCP server (read-only tools only)├── examples/mcp-configs/          # MCP client config templates├── tests/                         # Test suite├── smithery.yaml                  # Smithery marketplace config├── RELEASE_NOTES.md├── config.example.yaml└── pyproject.toml

Related Projects

Troubleshooting & Contributing

If you encounter any errors or issues, please send the error message, logs, or screenshots to [email protected]. Contributions are welcome!

Remote access (HTTPS) and limiting tools

By default vmware-monitor mcp speaks stdio to one local client and offers every tool. Two options change that (vmware-policy ≥ 1.21.0).

Serve over HTTPS so clients on other machines can connect. Every caller needs a bearer token:

vmware-audit token create alice          # prints the token once; give it to alicevmware-audit token list                  # names onlyvmware-audit token revoke alice          # refused from its next request, no restartvmware-monitor mcp --transport https --host 0.0.0.0 --port 8443 \    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \    --public-name mcp.example.com

Connect a client (Claude Code shown; any MCP client that supports streamable HTTP and custom headers works):

claude mcp add --transport http vmware-monitor https://mcp.example.com:8443/mcp \    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{  "mcpServers": {    "vmware-monitor": {      "type": "http",      "url": "https://mcp.example.com:8443/mcp",      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }    }  }}

• The server will not start without a token, refuses Host/Origin values outside --public-name, and checks before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
• Behind a TLS-terminating reverse proxy on the same machine use --transport http --host 127.0.0.1 --public-name mcp.example.com and pass the Authorization header through.
• Behind a load balancer or gateway on another machine, keep --transport https (a self-signed certificate is fine), list in --public-name the host name the balancer sends as Host, and have it forward Authorization. Its health probe can use GET /healthz, which needs no token and returns only {"status": "ok"} (vmware-policy ≥ 1.23.0).
• Send traceparent or X-Request-ID with each request to have it stored on the audit row; vmware-audit log --correlation-id ID then finds the calls behind one platform request.
• The audit log records each caller as token:<name>. Calls run side by side, with up to VMWARE_MCP_POOL_SIZE (default 2) sessions per target; each session is a login on the target, and a call waits at most 300 s for one.
• Everyone who can reach the endpoint acts with this server's account. Tokens identify callers; they grant nothing on the platform. Run one endpoint per privilege level.
• Several people or roles on one endpoint: run vmware-audit roles enable once, then give each token a role (vmware-audit token create NAME --role reader, or a role in roles.yaml naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".

Limiting tools: every tool of this server is read-only, so --expose read changes nothing here; it exists for the write-capable skills. Least privilege comes from the account the server uses.

Details: skills/vmware-monitor/references/setup-guide.md ("Serving MCP over HTTPS", "Limiting which tools are offered").

License

MIT