Summary
Connects Claude to VMware vSphere 8.x Workload Management APIs and Supervisor Kubernetes endpoints to provision and manage Tanzu Kubernetes clusters. Exposes 20 tools split across supervisor status checks, vSphere namespace lifecycle (create, update quotas, delete with guard rails), and TanzuKubernetesCluster operations including creation with dry-run previews, worker scaling, version upgrades, and kubeconfig extraction. Uses pyVmomi for vCenter REST calls and the Kubernetes Python client against the Supervisor API, auto-detecting cluster.x-k8s.io v1 or v1beta1. Best for platform teams managing containerized workloads on vSphere who need namespace provisioning, TKC deployments, and day-2 cluster operations accessible through natural language. Community project by a VMware engineer, not an official Broadcom release.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
VMware VKS
Author: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com This is a community-driven project by a VMware engineer, not an official VMware product. For official VMware developer tools see developer.broadcom.com.
MCP Skill + CLI for VMware vSphere Kubernetes Service (VKS) management — Supervisor clusters, vSphere Namespaces, and VKS Cluster lifecycle. 20 MCP tools.
Companion Skills
Part of the VMware MCP Skills family. Each skill handles a distinct domain — install only what you need.
| Skill | Scope | Tools | Install |
|---|---|---|---|
| vmware-aiops ⭐ entry point | VM lifecycle, deployment, guest ops, clusters | 31 | uv tool install vmware-aiops |
| vmware-monitor | Read-only monitoring, alarms, events, VM info | 8 | uv tool install vmware-monitor |
| vmware-storage | Datastores, iSCSI, vSAN | 11 | uv tool install vmware-storage |
| vmware-nsx | NSX networking: segments, gateways, NAT, IPAM | 31 | uv tool install vmware-nsx-mgmt |
| vmware-nsx-security | DFW microsegmentation, security groups, Traceflow | 20 | uv tool install vmware-nsx-security |
| vmware-aria | Aria Ops metrics, alerts, capacity planning | 18 | uv tool install vmware-aria |
Prerequisites
- Python 3.10+ — required for
uv tool install - vSphere 8.0+ — Workload Management (Supervisor) APIs require vSphere 8.x
- Workload Management enabled — WCP must be enabled on at least one compute cluster
- License — vSphere Kubernetes Service (Enterprise Plus or VMware Cloud Foundation)
Run vmware-vks check after setup to verify all requirements are met.
Quick Start
# Install
uv tool install vmware-vks
# Configure
mkdir -p ~/.vmware-vks
cp config.example.yaml ~/.vmware-vks/config.yaml
# Edit config.yaml with your vCenter host and username
echo "VMWARE_MY_VCENTER_PASSWORD=your_password" > ~/.vmware-vks/.env
chmod 600 ~/.vmware-vks/.env
# Verify
vmware-vks check
# Common operations
vmware-vks supervisor status domain-c1
vmware-vks namespace list
vmware-vks tkc list
vmware-vks tkc create my-cluster -n dev --version v1.28.4+vmware.1 --vm-class best-effort-large
vmware-vks tkc create my-cluster -n dev --apply
Common Workflows
Deploy a New TKC Cluster
- Check compatibility →
vmware-vks check - List available K8s versions →
vmware-vks tkc versions -n dev - Create namespace (if needed) →
vmware-vks namespace create dev --cluster domain-c1 --storage-policy <policy-id> --cpu 16000 --memory 32768 --apply(get the policy ID fromvmware-vks supervisor storage-policies) - Create TKC cluster →
vmware-vks tkc create dev-cluster -n dev --version v1.28.4+vmware.1 --control-plane 1 --workers 3 --vm-class best-effort-large --apply - Get kubeconfig →
vmware-vks kubeconfig get dev-cluster -n dev
Scale Workers for Load Testing
- Check current state →
vmware-vks tkc get dev-cluster -n dev - Scale up →
vmware-vks tkc scale dev-cluster -n dev --workers 6 - Monitor progress →
vmware-vks tkc get dev-cluster -n dev(watch phase) - Scale back down after test
Namespace Resource Management
- List namespaces →
vmware-vks namespace list - Check usage →
vmware-vks storage -n dev - Update quota →
vmware-vks namespace update dev --cpu 32000 --memory 65536
Tool Reference (20 tools)
Supervisor
| Tool | Description | Type |
|---|---|---|
check_vks_compatibility | vCenter version check + WCP status | Read |
get_supervisor_status | Supervisor cluster status and K8s API endpoint | Read |
list_supervisor_storage_policies | vCenter storage policies (policy ID, name, description) | Read |
Namespace
| Tool | Description | Type |
|---|---|---|
list_namespaces | All vSphere Namespaces with status | Read |
get_namespace | Namespace detail (quotas, storage, roles) | Read |
create_namespace | Create Namespace with dry-run preview | Write |
update_namespace | Modify quotas and storage policy | Write |
delete_namespace | Delete with TKC guard (rejects if clusters exist) | Write |
list_vm_classes | Available VM classes for TKC sizing | Read |
TKC
| Tool | Description | Type |
|---|---|---|
list_tkc_clusters | TanzuKubernetesCluster list with status | Read |
get_tkc_cluster | Cluster detail (nodes, health, conditions) | Read |
get_tkc_available_versions | Supported K8s versions on Supervisor | Read |
create_tkc_cluster | Create TKC with YAML plan + dry-run default | Write |
scale_tkc_cluster | Scale worker node count | Write |
upgrade_tkc_cluster | Upgrade K8s version | Write |
delete_tkc_cluster | Delete with workload guard | Write |
Access
| Tool | Description | Type |
|---|---|---|
get_supervisor_kubeconfig | Supervisor kubeconfig YAML | Read |
get_tkc_kubeconfig | TKC kubeconfig (stdout or file) | Read |
get_harbor_info | Embedded Harbor registry info (id, cluster, version, URL, health, storage used) | Read |
list_namespace_storage_usage | PVC list and capacity stats | Read |
Architecture
User (Natural Language)
↓
AI Agent (Claude Code / Goose / Cursor)
↓ reads SKILL.md
↓
vmware-vks CLI ─── or ─── vmware-vks MCP Server (stdio)
│
├─ Layer 1: pyVmomi → vCenter REST API
│ Supervisor status, storage policies, Namespace CRUD, VM classes, Harbor
│
└─ Layer 2: kubernetes client → Supervisor K8s API endpoint
TKC CR apply / get / delete (cluster.x-k8s.io API version auto-detected:
prefers v1 when Supervisor serves it, falls back to v1beta1 for vSphere 8.0)
Kubeconfig built in-memory from Layer 1 session token (no temp file on disk)
↓
vCenter Server 8.x+ (Workload Management enabled)
↓
Supervisor Cluster → vSphere Namespaces → TanzuKubernetesCluster
CLI Reference
# Pre-flight diagnostics
vmware-vks check
# Supervisor
vmware-vks supervisor status <cluster-id>
vmware-vks supervisor storage-policies
# Namespace
vmware-vks namespace list
vmware-vks namespace get <name>
vmware-vks namespace create <name> --cluster <id> --storage-policy <policy>
vmware-vks namespace create <name> --cluster <id> --storage-policy <policy> --apply
vmware-vks namespace update <name> [--cpu <mhz>] [--memory <mib>]
vmware-vks namespace delete <name>
vmware-vks namespace vm-classes
# VKS Cluster
vmware-vks tkc list [-n <namespace>]
vmware-vks tkc get <name> -n <namespace>
vmware-vks tkc versions -n <namespace>
vmware-vks tkc create <name> -n <namespace> [--version <v>] [--vm-class <c>]
vmware-vks tkc create <name> -n <namespace> --apply
vmware-vks tkc scale <name> -n <namespace> --workers <n>
vmware-vks tkc upgrade <name> -n <namespace> --version <v>
vmware-vks tkc delete <name> -n <namespace>
# Kubeconfig
vmware-vks kubeconfig supervisor -n <namespace>
vmware-vks kubeconfig get <cluster-name> -n <namespace> [-o <path>]
# Harbor & Storage
vmware-vks harbor
vmware-vks storage -n <namespace>
MCP Server
After uv tool install vmware-vks, start the MCP server with one command (v1.5.15+):
# Recommended — single command, no network re-resolve
vmware-vks mcp
# With a custom config path
VMWARE_VKS_CONFIG=/path/to/config.yaml vmware-vks mcp
Agent Configuration
Add to your AI agent's MCP config:
{
"mcpServers": {
"vmware-vks": {
"command": "vmware-vks",
"args": ["mcp"],
"env": {
"VMWARE_VKS_CONFIG": "~/.vmware-vks/config.yaml"
}
}
}
}
Alternative: uvx (no install) or legacy entry point
# Run without installing (requires PyPI access each launch)
uvx --from vmware-vks vmware-vks mcp
# Legacy entry point (still works, kept for backward compatibility)
vmware-vks-mcp
Behind a corporate TLS proxy? uvx may fail with
invalid peer certificate: UnknownIssuer. Use the recommendedvmware-vks mcpform above (no network needed), or setUV_NATIVE_TLS=true.
Safety
| Feature | Description |
|---|---|
| Read-heavy | 12/20 tools are read-only |
| Dry-run default | create_namespace, create_tkc_cluster, delete_namespace, delete_tkc_cluster all default to dry_run=True |
| TKC guard | delete_namespace rejects if TKC clusters exist inside |
| Workload guard | delete_tkc_cluster rejects if Deployments/StatefulSets are running |
| Credential safety | Passwords only from environment variables (.env file), never in config.yaml |
| In-memory kubeconfig | Supervisor/TKC kubeconfig (with vCenter session bearer token) is built as an in-memory dict and loaded via load_kube_config_from_dict() — never written to a temp file on disk (v1.5.18+) |
| Audit logging | All write operations logged to ~/.vmware-vks/audit.log |
| stdio transport | No network listener; MCP runs over stdio only |
Troubleshooting
"VKS not compatible" error
Workload Management must be enabled in vCenter. Check: vCenter UI -> Workload Management. Requires vSphere 8.x+ with Enterprise Plus or VCF license.
Namespace creation fails with "storage policy not found"
List policies first: vmware-vks supervisor storage-policies, then pass the Policy ID column value (not the display name) as --storage-policy.
TKC cluster stuck in "Creating" phase
Check Supervisor events in vCenter. Common causes: insufficient resources on ESXi hosts, network issues with NSX-T, or storage policy not available on target datastore.
Kubeconfig retrieval fails
Supervisor API endpoint must be reachable from the machine running vmware-vks. Check firewall rules for port 6443.
Scale operation has no effect
Verify the cluster is in "Running" phase before scaling. Clusters in "Creating" or "Updating" phase reject scale operations.
Delete namespace rejected unexpectedly
The namespace delete guard prevents deletion when TKC clusters exist inside. Delete all TKC clusters in the namespace first, then retry.
Version Compatibility
| vSphere / VCF | Support | Notes |
|---|---|---|
| 9.0 / 9.1 | ⚠ Not yet verified | Workload Management (Supervisor / WCP) API surface in vSphere 9 has not been tested by maintainers. Existing vSphere 8.x code paths should work but no guarantees until a lab run is completed — basic CRUD likely works, corner cases may need testing. File issues with check_vks_compatibility output if you run this on VCF 9. |
| 8.0+ | Full | Workload Management APIs available |
| 7.x | Not supported | WCP API surface is different; use vSphere 8.x |
Official Broadcom References
- SDKs: https://developer.broadcom.com/sdks — VCF Python SDK (unified SDK in VCF 9+)
- REST APIs: https://developer.broadcom.com/xapis — vSphere Automation API (Workload Management endpoints)
- CLI Tools: https://developer.broadcom.com/tools — kubectl-vsphere, PowerCLI 9.1
Related Projects
| Skill | Scope | Tools | Install |
|---|---|---|---|
| vmware-aiops ⭐ entry point | VM lifecycle, deployment, guest ops, clusters | 31 | uv tool install vmware-aiops |
| vmware-monitor | Read-only monitoring, alarms, events, VM info | 8 | uv tool install vmware-monitor |
| vmware-storage | Datastores, iSCSI, vSAN | 11 | uv tool install vmware-storage |
| vmware-nsx | NSX networking: segments, gateways, NAT, IPAM | 31 | uv tool install vmware-nsx-mgmt |
| vmware-nsx-security | DFW microsegmentation, security groups, Traceflow | 20 | uv tool install vmware-nsx-security |
| vmware-aria | Aria Ops metrics, alerts, capacity planning | 18 | uv tool install vmware-aria |
License
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →