Read-Only vSphere MCP Server

This project lets Codex read inventory from VMware vCenter. It exposes seven approved MCP tools and cannot create, update, delete, clone, power, or move anything.

Caveman Explanation

You -> Codex -> this MCP server -> vCenter
                                  |
                                  +-> read information only

Codex asks a question. The MCP server logs in to vCenter, performs an approved REST request, and returns the answer. The MCP server runs locally through standard input/output (stdio); it does not open a network port.

What You Need

You need:

1. The HTTPS address of your vCenter Server, such as https://vcenter.company.com.
2. A vCenter username.
3. That user's password.
4. The built-in Read-only role assigned at the inventory level you need, with propagation enabled.
5. Network or VPN access from your computer to vCenter.
6. Python 3.10 or newer, Git, and Codex.

The address alone is not enough. You need a username and password. You do not need a Broadcom developer API key. After login, vCenter returns a temporary session token automatically.

Send this request to your VMware administrator:

Please provide the HTTPS vCenter Server address and a dedicated service account with the built-in Read-only role. Assign it at the required inventory scope with propagation enabled. Please also provide the company CA certificate in PEM format if vCenter uses an internally signed certificate.

This project supports username/password authentication. If your company forces browser-only SSO or MFA, ask for a non-interactive read-only service account.

Install on macOS or Linux

git clone https://github.com/arjungowdal4601/vcenter_mcp.git
cd vcenter_mcp
python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
cp .env.example .env
chmod 600 .env

The version command must show Python 3.10 or newer. If python3 is older, use the newer executable installed on your computer, such as python3.13, for the virtual-environment command.

Open .env in a local text editor and replace the example values with your credentials. Do not paste the password into an AI chat.

Install on Windows PowerShell

git clone https://github.com/arjungowdal4601/vcenter_mcp.git
cd vcenter_mcp
py -3 --version
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
Copy-Item .env.example .env

The version command must show Python 3.10 or newer.

Open .env locally and replace the examples. If PowerShell blocks activation, you can still use .\.venv\Scripts\python.exe in the remaining commands.

Configure .env

Minimum configuration:

VSPHERE_HOST="https://vcenter.company.com"
VSPHERE_USERNAME="codex-readonly@vsphere.local"
VSPHERE_PASSWORD="your-real-password"
VSPHERE_VERIFY_SSL="true"
VSPHERE_TIMEOUT_SECONDS="30"

VSPHERE_HOST is the address used to open vCenter Server. Do not use an ESXi host address, the Broadcom documentation website, or an address ending in an API path such as /api or /sdk.

VSPHERE_USERNAME is the read-only vCenter account. Depending on your company, it may look like user@vsphere.local, DOMAIN\\user, or an email address.

VSPHERE_PASSWORD is that account's password. .env is ignored by Git and must never be committed.

VSPHERE_VERIFY_SSL should remain true. Turning verification off makes it possible to send credentials to an impostor server.

If your company uses a private certificate authority, add the absolute path to its PEM bundle:

VSPHERE_CA_BUNDLE="/Users/you/certificates/company-ca.pem"

On Windows, use a quoted absolute path:

VSPHERE_CA_BUNDLE="C:\\Certificates\\company-ca.pem"

Process environment variables override values in .env.

Connect the Server to Codex

Run the command from the repository directory after filling .env.

macOS or Linux:

codex mcp add vsphere -- "$(pwd)/.venv/bin/python" -m vsphere_mcp --env-file "$(pwd)/.env"

Windows PowerShell:

$root = (Get-Location).Path
codex mcp add vsphere -- "$root\.venv\Scripts\python.exe" -m vsphere_mcp --env-file "$root\.env"

The Codex registration stores only the Python command and .env path. It does not store the vCenter username or password.

Check the registration:

codex mcp get vsphere

Restart Codex after registering the server. Then ask:

Use the vSphere tools to list my virtual machines.

To replace an old registration:

codex mcp remove vsphere

Then run the appropriate codex mcp add command again.

Other MCP-compatible coding agents can run the same executable and arguments as a local stdio server. Their configuration format is agent-specific.

Available Tools

Tool	What it reads	REST endpoint
vsphere_list_vms	Visible virtual machines	GET /api/vcenter/vm
vsphere_get_vm	Details for one VM ID	GET /api/vcenter/vm/{vm}
vsphere_list_hosts	ESXi hosts	GET /api/vcenter/host
vsphere_list_clusters	Clusters	GET /api/vcenter/cluster
vsphere_list_datastores	Datastores	GET /api/vcenter/datastore
vsphere_list_datacenters	Datacenters	GET /api/vcenter/datacenter
vsphere_list_networks	Networks	GET /api/vcenter/network

vsphere_list_vms can filter by VM IDs, names, folders, datacenters, hosts, clusters, resource pools, and power states. Allowed power states are POWERED_ON, POWERED_OFF, and SUSPENDED.

Example prompts:

Use vSphere to list all VMs.
Show only powered-on VMs named web-server.
Get details for VM vm-42.
List my ESXi hosts and clusters.
List all datastores and datacenters visible to this account.
List the available vCenter networks.

The returned inventory depends on the account's vCenter permissions. An empty list can mean the login worked but the Read-only role was assigned at the wrong inventory scope.

Authentication

The MCP server performs this flow internally:

1. It sends the username and password to POST /api/session using HTTPS Basic authentication.
2. vCenter returns a temporary session token.
3. The server sends that token in the vmware-api-session-id header for REST reads.
4. If the token expires and vCenter returns HTTP 401, the server logs in once more and retries the read once.

The password is not an API key. The temporary session token is not something you obtain manually.

Security

• Only explicit read tools are registered with MCP.
• Every tool is marked read-only, non-destructive, and idempotent.
• There is no generic call_api tool.
• vCenter addresses must use HTTPS.
• Redirects are not followed, preventing credentials from being forwarded to another host.
• IDs and filters are validated before requests are sent.
• Passwords are excluded from configuration representations and errors.
• Real enforcement also comes from the vCenter account's Read-only role.

For stronger protection, create a dedicated service account instead of using a personal administrator account.

Troubleshooting

HTTP 401

vCenter rejected the username, password, or expired session. Confirm the credentials by signing in to the same VSPHERE_HOST. Browser-only MFA accounts will not work.

HTTP 403

The login worked, but the account lacks permission. Ask the administrator to assign the Read-only role at the correct inventory scope with propagation.

Certificate verification failed

Ask the administrator for the company CA certificate in PEM format and set VSPHERE_CA_BUNDLE. Do not solve production certificate errors by disabling verification.

Connection timeout or name error

Confirm the address, DNS, VPN, firewall, and port 443 access from your computer.

Codex cannot see the tools

Run codex mcp get vsphere, confirm the displayed Python and .env paths still exist, and restart Codex. Absolute paths break if the repository is moved; remove and add the registration again after moving it.

Tools return no inventory

The account may have the Read-only role at the wrong scope. vCenter only returns objects visible to that account.

Sharing

Share the GitHub repository, not your .env file. Each user should clone the project, create their own .env, and register their local copy with Codex. Never send vCenter passwords through Git, email, chat, screenshots, or tickets.

This version intentionally supports only local stdio. It does not provide a central HTTP MCP service.

Development

Install development dependencies and run the tests:

python -m pip install -e '.[dev]'
python -m pytest

Show the command-line help:

python -m vsphere_mcp --help

The automated tests use mocked vCenter responses. A real integration test requires a non-production vCenter address and read-only credentials.

Official References

• vSphere Automation API
• Create a vCenter REST session
• vSphere VM REST API
• Codex MCP documentation