Use this skill whenever the user needs to manage VMware storage — datastores, iSCSI targets, and vSAN clusters. Directly handles: browse datastores, scan for deployable images (OVA/ISO), configure iSCSI adapters and targets, check vSAN health and capacity. Always use this skill for "list datastores", "add iSCSI target", "check vSAN health", "browse datastore files", "scan for OVA images", or any storage-related VMware task. Do NOT use for VM lifecycle operations (use vmware-aiops), NSX networking (use vmware-nsx), or Kubernetes clusters (use vmware-vks). For load balancing/AVI/AKO use vmware-avi.
Instrucciones de origen · Vista previa de solo lectura
name
vmware-storage
description
Use this skill whenever the user needs to manage VMware storage — datastores, iSCSI targets, and vSAN clusters. Directly handles: browse datastores, scan for deployable images (OVA/ISO), configure iSCSI adapters and targets, check vSAN health and capacity. Always use this skill for "list datastores", "add iSCSI target", "check vSAN health", "browse datastore files", "scan for OVA images", or any storage-related VMware task. Do NOT use for VM lifecycle operations (use vmware-aiops), NSX networking (use vmware-nsx), or Kubernetes clusters (use vmware-vks). For load balancing/AVI/AKO use vmware-avi.
vmware-policy auto-installed as Python dependency (provides @vmware_tool decorator and audit logging). All write operations audited to ~/.vmware/audit.db. Credentials: Each vCenter/ESXi target requires a per-target password env var in ~/.vmware-storage/.env following the pattern VMWARE_<TARGET_NAME_UPPER>_PASSWORD (e.g., target "my-vcenter" → VMWARE_MY_VCENTER_PASSWORD). No webhooks or outbound network calls — this skill is local-only (stdio MCP + vSphere API). Audit logs written to ~/.vmware/audit.db (SQLite WAL, local only).
VMware Storage
Disclaimer: This is a community-maintained open-source project and is not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc. "VMware" and "vSphere" are trademarks of Broadcom. Source code is publicly auditable at github.com/zw008/VMware-Storage under the MIT license.
VMware vSphere storage management — 11 MCP tools for datastores, iSCSI, and vSAN.
Network reachability: vmkping <iscsi-target-ip> from the ESXi host must succeed BEFORE adding the target. Adding an unreachable target leaves the host in a degraded state, retrying forever.
Adapter sanity: iscsi status first — if already enabled, do not "re-enable"; just add the target.
Idempotency: add-target is idempotent (re-adding same IP is a no-op), but remove-target is not safely reversible mid-IO. Always verify no LUNs from this target are in use before removing.
Existing targets: list them first; some sites add targets one-per-host while others use cluster-wide. Check site convention.
Steps:
iscsi status esxi-01 → confirm adapter state and existing targets
iscsi enable esxi-01 --dry-run then real (skip if already enabled)
iscsi add-target esxi-01 <ip> --dry-run then real (auto-rescans on success)
iscsi status esxi-01 again → confirm target listed AND devices appearing
If devices missing 30+ sec after add: iscsi rescan esxi-01 once more, then check ESXi-side vmkping and target ACL
Find Deployable Images Across Datastores
Judgment: image search is read-only and safe, but blind scanning of every datastore is slow on large estates. Filter first.
datastore list → get the inventory; ignore datastores marked inaccessible or low free space
datastore scan-images <ds> on the datastore most likely to hold images (typically named iso-*, templates, or central nfs-shared)
If unsure where images live: scan multiple in parallel via separate calls; results are cached in the local registry
datastore browse <ds> --pattern "*.iso" for ad-hoc searches; pattern is glob, not regex
If datastore not found: name is case-sensitive. datastore list --target <vc> to verify exact spelling.
For filtered queries against the cache: use list_cached_images MCP tool with image_type and datastore parameters — avoids re-scanning.
vSAN Health Assessment
Judgment: vSAN problems often masquerade as vSphere problems and vice-versa. Check both planes — if vSAN is healthy but VMs are slow, the issue is at the compute or network layer, not storage.
vsan health <cluster> → look beyond green/red — check disk group state, network partitioning, and cluster member counts. A "yellow" disk group is the early warning of a failure.
vsan capacity <cluster> → utilization > 70% triggers slack-space risk; > 80% impedes resync; never let prod cross 80%.
Cross-check vmware-monitor health alarms for vSAN-related alarms (HCL warnings, network anomalies)
If vSAN not enabled on this cluster: check cluster type via vmware-monitor inventory clusters; vSAN is opt-in, not default
For deep investigation, follow references/investigation-protocol.md (in companion skill) — vSAN issues frequently fail the Mechanism criterion (capacity is correlated, not causal)
Multi-Target Operations
All commands accept --target <name> to operate against a specific vCenter or ESXi host from your config:
# Default target (first in config.yaml)
vmware-storage datastore list
# Specific target
vmware-storage datastore list --target prod-vcenter
vmware-storage iscsi status esxi-lab --target lab-esxi
Usage Mode
Scenario
Recommended
Why
Local/small models (Ollama, Qwen)
CLI
~2K tokens vs ~8K for MCP
Cloud models (Claude, GPT-4o)
Either
MCP gives structured JSON I/O
Automated pipelines
MCP
Type-safe parameters, structured output
MCP Tools (11 — 6 read, 5 write)
All MCP tools accept an optional target parameter to select which vCenter/ESXi to connect to.
Category
Tool
Type
Description
Datastore
list_all_datastores
Read
List datastores with capacity, usage %, VM count
browse_datastore
Read
Browse files with optional path and glob pattern
scan_datastore_images
Read
Find OVA/ISO/OVF/VMDK in a datastore
list_cached_images
Read
Query local image registry with type/datastore filters
iSCSI
storage_iscsi_status
Read
Show adapter status, HBA device, IQN, send targets
storage_iscsi_enable
Write
Enable software iSCSI adapter on a host
storage_iscsi_add_target
Write
Add iSCSI send target (IP + port) and rescan
storage_iscsi_remove_target
Write
Remove iSCSI send target and rescan
storage_rescan
Write
Rescan all HBAs and VMFS volumes
vSAN
vsan_health
Read
Cluster health summary and disk group details
vsan_capacity
Read
Total/used/free capacity in GB and usage %
Read/write split: 6 tools are read-only, 5 modify state. Write tools require explicit parameters (host name, IP address) and are audit-logged.
Full CLI reference with all options and output formats: see references/cli-reference.md
Troubleshooting
iSCSI enable fails with "already enabled"
Not an error. The software iSCSI adapter is already active on that host. The response includes the current HBA device name and IQN. Run iscsi status to see configured send targets.
"Datastore not found" when browsing
Datastore names are case-sensitive. Run vmware-storage datastore list to get the exact name. Common mistakes: Datastore1 vs datastore1, trailing spaces.
vSAN health shows "unknown" status
vSAN health checks require a vCenter connection (not standalone ESXi). The full VsanVcClusterHealthSystem runs via vCenter's vSAN Health Service. If connected to a standalone ESXi host, vSAN queries will fail or return limited info.
Rescan doesn't discover new LUNs
After adding iSCSI targets, the storage subsystem may need 10-30 seconds to enumerate new LUNs. Steps to resolve:
Verify the target IP is reachable from the ESXi host (vmkping from ESXi shell)
Check that the iSCSI target is correctly configured: vmware-storage iscsi status <host>
Wait 15-30 seconds, then rescan again: vmware-storage iscsi rescan <host>
"Password not found" error
The password environment variable is missing. Variable names follow the pattern VMWARE_<TARGET_NAME_UPPER>_PASSWORD where hyphens become underscores. Example: target my-vcenter needs VMWARE_MY_VCENTER_PASSWORD. Check your ~/.vmware-storage/.env file.
Doctor reports ".env permissions too open"
The .env file contains passwords and must have owner-only permissions:
chmod 600 ~/.vmware-storage/.env
Connection timeout to vCenter
The doctor command tests connectivity with a 5-second TCP timeout. If your vCenter is on a high-latency network, the check may fail even though the connection works. Use --skip-auth to bypass both connectivity and auth checks, then test manually.
invalid peer certificate: UnknownIssuer when starting MCP via uvx
Corporate TLS proxies inject certificates that uv's bundled CA store doesn't trust. Use the recommended vmware-storage mcp form (no PyPI re-resolve), or set export UV_NATIVE_TLS=true to make uv use system CAs.
Safety
No VM operations: This skill cannot power on/off, create, delete, or modify VMs — that scope belongs to vmware-aiops
Read-heavy: 6 of 11 tools are read-only (list, browse, scan, status, health, capacity)
Audit logging: All operations (including reads) are logged to ~/.vmware/audit.db (SQLite WAL, via vmware-policy) with timestamp, user, target, operation, parameters, and result
Double confirmation: CLI write commands (iSCSI enable, add/remove target) require two separate "Are you sure?" prompts before executing
Dry-run mode: All write commands support --dry-run to preview API calls without executing
Input validation: IP addresses validated via ipaddress.ip_address(), ports checked for 1-65535 range, host/cluster/datastore names looked up before operations
Prompt injection defense: Datastore file names and paths from vSphere are sanitized via _sanitize() — strips control characters (C0/C1), truncates to 500 chars — preventing malicious file names from injecting instructions into downstream LLM agents
Credential safety: Passwords loaded only from environment variables (.env file), never from config.yaml; .env permissions are checked at startup
Full security details: see references/setup-guide.md
Setup
uv tool install vmware-storage
mkdir -p ~/.vmware-storage
cp config.example.yaml ~/.vmware-storage/config.yaml
# Edit config.yaml with your vCenter/ESXi targets# Add to ~/.vmware-storage/.env (create if missing, chmod 600):# VMWARE_MY_VCENTER_PASSWORD=<your-password>chmod 600 ~/.vmware-storage/.env
vmware-storage doctor
All tools are automatically audited via vmware-policy. Audit logs: vmware-audit log --last 20
Full setup guide with multi-target config, MCP server setup, and Docker: see references/setup-guide.md
Architecture
User (natural language)
↓
AI Agent (Claude Code / Goose / Cursor)
↓ reads SKILL.md
vmware-storage CLI or MCP server (stdio transport)
↓ pyVmomi (vSphere SOAP API)
vCenter Server / ESXi
↓
Datastores / iSCSI / vSAN
The MCP server uses stdio transport (local only, no network listener). Connections to vSphere use SSL/TLS on port 443.
Audit & Safety
All operations are automatically audited via vmware-policy (@vmware_tool decorator):
Every tool call logged to ~/.vmware/audit.db (SQLite, framework-agnostic)
