Summary
Connects Claude to VMware NSX Policy API (NSX-T 3.0+ and NSX 4.x) with 31 tools split across segments, Tier-0/Tier-1 gateways, NAT rules, static routes, IP pools, and health checks. Written by a VMware engineer but not an official product. Useful when you need to programmatically create overlay networks, configure SNAT/DNAT, troubleshoot VM connectivity by tracing segments and ports, or check transport node and edge cluster status. All write operations support dry-run mode. Part of a larger suite that includes separate servers for vSphere operations, storage, Tanzu, NSX security (DFW/microsegmentation), and Aria Ops. Install via uv or pip, configure with YAML credentials, and run the MCP server with a single command.
Keeps your Mac awake while Claude Code, Codex or Cursor works. Lets it sleep when they are done.
Try free for 7 days →
Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →
Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →VMware NSX
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.
VMware NSX networking management: segments, gateways, NAT, routing, IPAM — 33 MCP tools, domain-focused.
NSX Policy API skill for NSX-T 3.0+ and NSX 4.x.
Companion Skills
| Skill | Scope | Tools | Install |
|---|---|---|---|
| vmware-aiops ⭐ entry point | VM lifecycle, deployment, guest ops, clusters | 49 | uv tool install vmware-aiops |
| vmware-monitor | Read-only monitoring, alarms, events, VM info | 27 | uv tool install vmware-monitor |
| vmware-storage | Datastores, iSCSI, vSAN | 11 | uv tool install vmware-storage |
| vmware-vks | Tanzu Namespaces, TKC cluster lifecycle | 20 | uv tool install vmware-vks |
| vmware-nsx-security | DFW microsegmentation, security groups, Traceflow | 21 | uv tool install vmware-nsx-security |
| vmware-aria | Aria Ops metrics, alerts, capacity planning | 28 | uv tool install vmware-aria |
| vmware-avi | AVI/NSX ALB load balancing, AKO | 28 | uv tool install vmware-avi |
| vmware-harden | Compliance baselines, drift detection | 6 | uv tool install vmware-harden |
Quick Install
# Via PyPI
uv tool install vmware-nsx-mgmt
# Or pip
pip install vmware-nsx-mgmt
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-nsx-mgmt
Configuration
mkdir -p ~/.vmware-nsx
cp config.example.yaml ~/.vmware-nsx/config.yaml
# Edit with your NSX Manager credentials
echo "VMWARE_NSX_NSX_PROD_PASSWORD=your_password" > ~/.vmware-nsx/.env
chmod 600 ~/.vmware-nsx/.env
# Verify
vmware-nsx doctor
What This Skill Does
| Category | Tools | Count | Read / Write |
|---|---|---|---|
| Segments | list, get, create, update, delete | 5 | 2R / 3W |
| Tier-0 Gateways | list, get, BGP neighbors, configure BGP | 4 | 3R / 1W |
| Tier-1 Gateways | list, get, create, update, delete | 5 | 2R / 3W |
| NAT | list, create, delete | 3 | 1R / 2W |
| Static Routes | list, create, delete | 3 | 1R / 2W |
| IP Pools | list, usage, create, delete | 4 | 2R / 2W |
| Fabric Inventory | transport zones, transport nodes, edge clusters | 3 | 3R / 0W |
| Health & Troubleshooting | alarms, transport node status, edge cluster status, manager status, port status, VM-to-segment | 6 | 6R / 0W |
Total: 33 tools (20 read-only + 13 write)
Common Workflows
Create an App Network (Segment + T1 Gateway + NAT)
- Create gateway:
vmware-nsx gateway create-t1 app-t1 --edge-cluster edge-cluster-01 --tier0 tier0-gw - Create segment:
vmware-nsx segment create app-web-seg --name app-web-seg --tz <tz-overlay-path> --subnet 10.10.1.1/24 - Add SNAT:
vmware-nsx nat create app-t1 --action SNAT --source 10.10.1.0/24 --translated 172.16.0.10 - Verify:
vmware-nsx segment listandvmware-nsx nat list app-t1
Use --dry-run to preview any write command first.
Check Network Health
- Manager status:
vmware-nsx health manager-status - Transport nodes:
vmware-nsx health transport-nodes - Edge clusters:
vmware-nsx health edge-clusters - Alarms:
vmware-nsx health alarms --severity HIGH(exact-match filter; query each severity separately)
Troubleshoot VM Connectivity
- Find VM's segment:
vmware-nsx troubleshoot vm-segment <vm-display-name> - Check port realized state:
vmware-nsx troubleshoot port-status <segment-id>(all ports on the segment: attachment, realized bindings, transport nodes) - Check routes:
vmware-nsx gateway routes-t1 app-t1 - Check BGP:
vmware-nsx gateway bgp-neighbors tier0-gw
MCP Tools (33 — 20 read, 13 write)
| Category | Tools | Type |
|---|---|---|
| Segments | list_segments, get_segment, create_segment, update_segment, delete_segment | Read/Write |
| Tier-0 GW | list_tier0_gateways, get_tier0_gateway, get_bgp_neighbors, configure_tier0_bgp | Read/Write |
| Tier-1 GW | list_tier1_gateways, get_tier1_gateway, create_tier1_gateway, update_tier1_gateway, delete_tier1_gateway | Read/Write |
| NAT | list_nat_rules, create_nat_rule, delete_nat_rule | Read/Write |
| Static Routes | list_static_routes, create_static_route, delete_static_route | Read/Write |
| IP Pools | list_ip_pools, get_ip_pool_usage, create_ip_pool, delete_ip_pool | Read/Write |
| Fabric | list_transport_zones, list_transport_nodes, list_edge_clusters | Read |
| Health | list_nsx_alarms (per-severity, exact match), get_transport_node_status, get_edge_cluster_status, get_nsx_manager_status | Read |
| Troubleshoot | get_logical_port_status (realized state of all ports on a segment), get_segment_port_for_vm (lookup by VM display name) | Read |
Full per-tool endpoints and methods: skills/vmware-nsx/references/capabilities.md.
CLI
# Segments
vmware-nsx segment list
vmware-nsx segment get app-web-seg
vmware-nsx segment create app-web-seg --name app-web-seg --tz <tz-overlay-path> --subnet 10.10.1.1/24
vmware-nsx segment delete app-web-seg
# Gateways
vmware-nsx gateway list-t0
vmware-nsx gateway list-t1
vmware-nsx gateway create-t1 app-t1 --edge-cluster edge-cluster-01 --tier0 tier0-gw
vmware-nsx gateway bgp-neighbors tier0-gw
vmware-nsx gateway routes-t1 app-t1
# NAT
vmware-nsx nat list app-t1
vmware-nsx nat create app-t1 --action SNAT --source 10.10.1.0/24 --translated 172.16.0.10
vmware-nsx nat delete-rule --tier1 app-t1 --rule-id rule-01
# Static Routes
vmware-nsx route list app-t1
vmware-nsx route create app-t1 --network 192.168.100.0/24 --next-hop 10.10.1.254
# IP Pools
vmware-nsx ippool list
vmware-nsx ippool create tep-pool
vmware-nsx ippool add-subnet tep-pool --start 192.168.100.10 --end 192.168.100.50 --cidr 192.168.100.0/24
# Health & Troubleshooting
vmware-nsx health alarms --severity HIGH # exact match: LOW | MEDIUM | HIGH | CRITICAL
vmware-nsx health transport-nodes
vmware-nsx health manager-status
vmware-nsx troubleshoot vm-segment my-vm-01 # VM display name
vmware-nsx troubleshoot port-status app-web-seg # segment ID
# Diagnostics
vmware-nsx doctor
MCP Server
After uv tool install vmware-nsx-mgmt, start the MCP server with one command (v1.5.15+):
# Recommended — single command, no network re-resolve
vmware-nsx mcp
# Or via Docker
docker compose up -d
Agent Configuration
Add to your AI agent's MCP config:
{
"mcpServers": {
"vmware-nsx": {
"command": "vmware-nsx",
"args": ["mcp"],
"env": {
"VMWARE_NSX_CONFIG": "~/.vmware-nsx/config.yaml"
}
}
}
}
Alternative: uvx (no install) or legacy entry point
# Run without installing (requires PyPI access each launch)
uvx --from vmware-nsx-mgmt vmware-nsx mcp
# Legacy entry point (still works, kept for backward compatibility)
vmware-nsx-mcp
Behind a corporate TLS proxy? uvx may fail with
invalid peer certificate: UnknownIssuer. Use the recommendedvmware-nsx mcpform above (no network needed), or setUV_NATIVE_TLS=true.
More agent config templates (Claude Code, Cursor, Goose, Continue, etc.) in examples/mcp-configs/.
Version Compatibility
| NSX Version | Support | Notes |
|---|---|---|
| NSX 9.1 | Full | Policy API supported. Note: VDS 7.0+ required (N-VDS removed in NSX 9). |
| NSX 9.0 | Full | Policy API supported. Note: bare-metal agent / physical-server L2 overlay removed. |
| NSX 4.x | Full | Latest Policy API, all features |
| NSX-T 3.2 | Full | All features work |
| NSX-T 3.1 | Full | Minor route table format differences |
| NSX-T 3.0 | Compatible | IP pool subnet API introduced here |
| NSX-T 2.5 | Limited | Policy API incomplete; some tools may fail |
| NSX-V (6.x) | Not supported | Different API (SOAP-based) |
VCF Compatibility
| VCF Version | Bundled NSX | Support |
|---|---|---|
| VCF 9.1 | NSX 9.1 | Full |
| VCF 9.0 | NSX 9.0 | Full |
| VCF 5.x | NSX 4.x | Full |
| VCF 4.3-4.5 | NSX-T 3.1-3.2 | Full |
Official Broadcom References
- SDKs: https://developer.broadcom.com/sdks — VMware NSX for Python SDK (official; future migration target), VCF Python SDK
- REST APIs: https://developer.broadcom.com/xapis — NSX-T Data Center REST API (this skill uses the Policy API subset)
- CLI Tools: https://developer.broadcom.com/tools — VCF PowerCLI 9.1 (includes NSX cmdlets)
Safety
| Feature | Description |
|---|---|
| Read-heavy | 20/33 tools are read-only |
| Double confirmation | CLI write commands require two prompts |
| Dry-run mode | All write commands support --dry-run preview |
| MCP delete preview | The five MCP delete tools preview by default: without confirm=True they return blast_radius (what would be removed, blockers, unmeasured) and delete nothing. confirm=True is refused while a blocker remains or a read failed |
| Dependency checks | Segment delete refuses while ports are attached; Tier-1 delete refuses, deleting nothing, while segments, NAT rules, static routes, interfaces or VPN / DNS forwarder / LB services still depend on it (--dry-run runs the same check). On MCP, IP pool delete refuses while addresses are allocated — Policy ip-allocations, or NSX's pool_usage count, which also covers addresses Policy does not list (e.g. TEP pools) — and when pool_usage cannot be read. NAT rule and static route deletes have no blockers; their preview shows the rule's match or the route's network and next hops |
| Input validation | CIDR, IP, VLAN IDs, gateway existence validated |
| Audit logging | All operations logged to ~/.vmware-nsx/audit.log |
| No firewall ops | Cannot create/modify DFW rules or security groups |
| Credential safety | Passwords only from environment variables |
| Prompt injection defense | NSX object names sanitized before output |
Troubleshooting
| Problem | Cause & Fix |
|---|---|
| "Segment not found" | Policy API uses segment id, not display_name. Run segment list to get the exact ID. |
| NAT creation fails "gateway not found" | NAT requires a Tier-1 (or Tier-0) gateway. Verify with gateway list-t1. Gateway must have an edge cluster. |
| BGP neighbor stuck in Connect/Active | Peer unreachable, ASN mismatch, TCP 179 blocked, or MD5 password mismatch. |
| Transport node "degraded" | TEP unreachable (check MTU >= 1600), NTP sync issues, or host switch config mismatch. |
| "Password not found" | Variable naming: VMWARE_NSX_<TARGET_UPPER>_PASSWORD (hyphens to underscores). Check ~/.vmware-nsx/.env. |
| Connection timeout | Use vmware-nsx doctor --skip-auth to bypass auth checks on high-latency networks. |
Remote access (HTTPS) and limiting tools
By default vmware-nsx 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 alice
vmware-audit token list # names only
vmware-audit token revoke alice # refused from its next request, no restart
vmware-nsx 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-nsx https://mcp.example.com:8443/mcp \
--header "Authorization: Bearer $VMWARE_MCP_TOKEN"
{
"mcpServers": {
"vmware-nsx": {
"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.comand pass theAuthorizationheader through. - Behind a load balancer or gateway on another machine, keep
--transport https(a self-signed certificate is fine), list in--public-namethe host name the balancer sends asHost, and have it forwardAuthorization. Its health probe can useGET /healthz, which needs no token and returns only{"status": "ok"}(vmware-policy ≥ 1.23.0). - Send
traceparentorX-Request-IDwith each request to have it stored on the audit row;vmware-audit log --correlation-id IDthen finds the calls behind one platform request. - The audit log records each caller as
token:<name>. Calls run side by side, with or without a target: each target keeps up toVMWARE_MCP_POOL_SIZEsessions (default 2), and each session is a login on the target. A call that finds them all busy 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 enableonce, then give each token a role (vmware-audit token create NAME --role reader, or a role inroles.yamlnaming 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".
Offer only read tools, plus the writes you choose:
vmware-nsx mcp --expose read --allow-write create_ip_pool
# or: VMWARE_NSX_MCP_EXPOSE=read VMWARE_NSX_MCP_ALLOW_WRITE=create_ip_pool vmware-nsx mcp
Tools not offered do not appear in the client's tool list. A bad value or an unknown write tool stops the server (exit 2). This limits what clients are offered; it is not authorization, so the account itself should be least-privilege.
Details: skills/vmware-nsx/references/setup-guide.md ("Serving MCP over HTTPS", "Limiting which tools are offered").
License
Featured
Keeps your Mac awake while Claude Code, Codex or Cursor works. Lets it sleep when they are done.
Try free for 7 days →Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →