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.

English | 中文

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 list and vmware-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 recommended vmware-nsx mcp form above (no network needed), or set UV_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.com and pass the Authorization header through.
The audit log records each caller as token:<name>. Calls run side by side, with or without a target: each target keeps up to VMWARE_MCP_POOL_SIZE sessions (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.

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

MIT

Development Status
- 4 - Beta
License
- OSI Approved :: MIT License
Programming Language
- Python :: 3
Topic
- System :: Networking

Metadata

Development Status
- 4 - Beta
License
- OSI Approved :: MIT License
Programming Language
- Python :: 3
Topic
- System :: Networking

Release files for vmware-nsx-mgmt 1.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vmware-nsx-mgmt 1.14.0
File	Size	Uploaded
vmware_nsx_mgmt-1.14.0.tar.gz	356.0 kB	Oct 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vmware-nsx-mgmt 1.14.0
File	Interpreter	ABI	Platform	Reset
vmware_nsx_mgmt-1.14.0-py3-none-any.whl 109.5 kB Oct 15, 2026	Python 3	none	any	Details

Total release size: 465.5 kB

Release files / vmware_nsx_mgmt-1.14.0.tar.gz

Download URL	vmware_nsx_mgmt-1.14.0.tar.gz
Size	356.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`a16d880d02e5cac9e406319938b2b9a9644334c5b2c465628400170cb41db769`
BLAKE2b-256 checksum How to use checksums	`7bc02cfd53c138c2a5876bb2bc9be5e6b8a8305c6f9c3302700c3dce746ae85c`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.12`

Release files / vmware_nsx_mgmt-1.14.0-py3-none-any.whl

Download URL	vmware_nsx_mgmt-1.14.0-py3-none-any.whl
Size	109.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`12e8ded7454e238915e6c98cb204e5a27221475e6ece9021d6463fb68b1021d3`
BLAKE2b-256 checksum How to use checksums	`50640349382e2e217217849a87b6d85cf6bfd4bf57bebf50eae505469fe870c6`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.12`