Read-Only vSphere MCP Server

Connect Codex, Cursor, Claude Code, or another MCP-compatible coding agent to VMware vCenter and ask questions about virtual machines, hosts, clusters, datastores, datacenters, and networks.

This server is intentionally read-only. It can fetch information. It cannot create, delete, modify, clone, power on, power off, connect, or disconnect VMware resources.

The Three Things You Need to Know

1. The vCenter address alone is not enough.

2. You need a vCenter username and password with read-only permission.

3. You do not need to buy or request a Broadcom or VMware developer API key.

The server uses your username and password to obtain a temporary vCenter session token. It manages that token automatically.

Related MCP server: VMware-Monitor

Caveman Explanation

You ask:       "Show my virtual machines."
Coding agent:  asks the MCP server
MCP server:    logs in to vCenter and asks for information
vCenter:       checks read-only permission and returns information
MCP server:    gives the answer to the coding agent

Another way to remember it:

vCenter address = location of the house
Username        = your name
Password        = key to the door
Session token   = temporary visitor badge created after login

The address, username, and password are required. The temporary badge is created by the software.

What This Project Uses

• vSphere Automation REST API for common inventory information.

• Virtual Infrastructure JSON API, called VI/JSON, for deeper managed-object properties on vCenter 8.0 Update 1 and newer.

• Model Context Protocol, called MCP, so coding agents can call the read-only functions as tools.

SOAP/Web Services is documented as a possible legacy fallback but is not used by this implementation.

Requirements

Information from your VMware administrator

Software on your computer

• Git.

• Python 3.10 or newer.

• Network or VPN access to the vCenter address.

• Codex, Cursor, Claude Code, or another MCP client.

Things you do not need

• A Broadcom website account for the MCP server.

• A VMware developer API key.

• An ESXi root password.

• vCenter Administrator permission.

• An OpenAI API key when you are already signed in to the Codex app or CLI.

Message to send your VMware administrator

You can send this message without changing it:

Please create a dedicated vCenter service account for a read-only MCP integration. Assign the built-in Read-only role at the required vCenter inventory scope and enable Propagate to children. Please provide the vCenter HTTPS address, service-account username and password, and the CA certificate chain in PEM format if vCenter uses an internal certificate authority. Administrator access is not required.

Fastest Installation: Guided Setup

The guided setup is the recommended path. It creates a private Python environment, installs the project, asks the required questions, creates .env, checks the vCenter connection, detects the VI/JSON version, and optionally registers the server with Codex.

Repository URL: https://github.com/arjungowdal4601/vcenter_mcp.git.

macOS or Linux

git clone "https://github.com/arjungowdal4601/vcenter_mcp.git" vm_ware_mcp
cd vm_ware_mcp
python3 scripts/bootstrap.py

Windows PowerShell

git clone "https://github.com/arjungowdal4601/vcenter_mcp.git" vm_ware_mcp
cd vm_ware_mcp
py scripts\bootstrap.py

Questions asked by the wizard

The wizard asks for:

1. vCenter address, such as https://vcenter.company.com.

2. Read-only vCenter username.

3. vCenter password. Input is hidden.

4. Optional company CA certificate path.

5. Whether the MCP server should be registered with Codex.

The password is entered locally in the terminal. It is not printed and is not copied into Codex configuration.

The wizard refuses to silently overwrite an existing .env file or Codex registration. It asks first.

Successful setup

You should see messages similar to:

Connection successful. Visible datacenters: 2.
Detected VI/JSON release: 8.0.3.0.
Configuration saved to /path/to/vm_ware_mcp/.env.
Codex registration completed. The password remains only in .env.

Restart the coding agent after installation.

Understanding the .env File

.env is a local configuration file. It contains the vCenter address and credentials used by the MCP server.

The wizard creates it automatically. You may also create it manually by copying .env.example:

cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env

Example:

VSPHERE_HOST="https://vcenter.company.com"
VSPHERE_USERNAME="mcp-reader@vsphere.local"
VSPHERE_PASSWORD="replace-with-the-real-password"
VSPHERE_VERIFY_SSL="true"
VSPHERE_CA_BUNDLE="/absolute/path/to/company-ca.pem"
VSPHERE_VI_JSON_RELEASE="8.0.3.0"
VSPHERE_TIMEOUT_SECONDS="30"
MCP_TRANSPORT="stdio"
MCP_HOST="127.0.0.1"
MCP_PORT="8000"

Every .env setting explained

Process environment variables take priority over values loaded from .env.

What exactly is VSPHERE_HOST?

Use the same base address that you use to open the vSphere Client in a browser:

Correct:   https://vcenter.company.com
Correct:   https://10.20.30.40
Wrong:     https://developer.broadcom.com
Wrong:     https://esxi-host.company.com
Wrong:     https://vcenter.company.com/ui
Wrong:     user:password@vcenter.company.com

The MCP server adds /api and /sdk/vim25/... paths itself.

Certificate verification

Production use must keep:

VSPHERE_VERIFY_SSL="true"

If setup reports CERTIFICATE_VERIFY_FAILED, ask the VMware administrator for the CA certificate chain in PEM format, save it locally, and set:

VSPHERE_CA_BUNDLE="/absolute/path/to/company-vcenter-ca.pem"

Setting verification to false hides certificate problems and can expose the username and password to an impersonated server. It is not recommended.

Protecting .env

• .env is excluded by .gitignore.

• The wizard uses owner-only file permissions on macOS and Linux.

• Never commit, email, paste into chat, or publish .env.

• Never place the password directly in README.md, Codex config.toml, Cursor mcp.json, or Claude configuration.

• Rotate the password immediately if it is accidentally exposed.

Authentication Explained

REST login

MCP server
  -> POST https://vcenter.company.com/api/session
  -> sends vCenter username and password with HTTPS Basic authentication
  <- receives temporary session token
  -> sends token in vmware-api-session-id header for later GET requests

Broadcom calls the session header api_key_auth in parts of the API reference. That does not mean you must obtain a developer key. The session value is generated by vCenter after login.

VI/JSON login

MCP server
  -> discovers the compatible API release
  -> calls SessionManager/Login with the same username and password
  <- receives another temporary session token
  -> uses that token for deep managed-object property reads

MFA and federated login

The current server supports non-interactive username/password authentication. If your organization requires browser-based MFA for every login, ask for a dedicated non-interactive read-only service account. SAML, browser MFA, delegated user identity, and certificate login are not implemented.

Installing Manually

Use this section when you do not want the guided bootstrap.

macOS or Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
cp .env.example .env
vsphere-mcp-setup

Windows PowerShell

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
Copy-Item .env.example .env
vsphere-mcp-setup

To rerun only the wizard later:

vsphere-mcp-setup

Using the Server with Codex

The wizard registers Codex automatically when codex is available. Codex starts the local stdio process when a session needs it. You do not manually start a web server.

Check the registration

codex mcp get vsphere
codex mcp list

Restart the Codex app, CLI, or IDE extension after changing MCP configuration.

Manual Codex registration

macOS/Linux example:

codex mcp add vsphere -- \
  "/absolute/path/to/vm_ware_mcp/.venv/bin/python" \
  -m vsphere_mcp \
  --env-file "/absolute/path/to/vm_ware_mcp/.env" \
  --transport stdio

Windows PowerShell example:

codex mcp add vsphere -- `
  "C:\absolute\path\to\vm_ware_mcp\.venv\Scripts\python.exe" `
  -m vsphere_mcp `
  --env-file "C:\absolute\path\to\vm_ware_mcp\.env" `
  --transport stdio

Equivalent ~/.codex/config.toml entry on macOS/Linux:

[mcp_servers.vsphere]
command = "/absolute/path/to/vm_ware_mcp/.venv/bin/python"
args = [
  "-m",
  "vsphere_mcp",
  "--env-file",
  "/absolute/path/to/vm_ware_mcp/.env",
  "--transport",
  "stdio",
]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60

The configuration contains the path to .env, not the password.

Official reference: Codex MCP documentation.

Using the Server with Cursor

Cursor supports local stdio MCP servers through mcp.json.

Global macOS/Linux configuration at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "vsphere": {
      "command": "/absolute/path/to/vm_ware_mcp/.venv/bin/python",
      "args": [
        "-m",
        "vsphere_mcp",
        "--env-file",
        "/absolute/path/to/vm_ware_mcp/.env",
        "--transport",
        "stdio"
      ]
    }
  }
}

For a project-only installation, put the same JSON in .cursor/mcp.json inside that project.

On Windows, use the absolute .venv\\Scripts\\python.exe path and escape each backslash as \\ in JSON.

Restart Cursor, open MCP settings, and verify that vsphere is connected and its tools are enabled.

Official reference: Cursor MCP documentation.

Using the Server with Claude Code

Register it for the current user:

claude mcp add --scope user vsphere -- \
  "/absolute/path/to/vm_ware_mcp/.venv/bin/python" \
  -m vsphere_mcp \
  --env-file "/absolute/path/to/vm_ware_mcp/.env" \
  --transport stdio

Then check the MCP status inside Claude Code or run its MCP listing command.

Official reference: Claude Code MCP documentation.

Using Another MCP-Compatible Agent

Any client that supports local stdio MCP servers needs the same two values:

command: /absolute/path/to/vm_ware_mcp/.venv/bin/python
arguments:
  -m
  vsphere_mcp
  --env-file
  /absolute/path/to/vm_ware_mcp/.env
  --transport
  stdio

Use absolute paths. Do not put the vCenter password in the agent configuration.

Available Tools

The MCP server exposes exactly nine tools.

VM filters

vsphere_list_vms supports:

• vms: VM IDs such as vm-42.

• names: exact VM names.

• folders: folder IDs.

• datacenters: datacenter IDs.

• hosts: ESXi host IDs.

• clusters: cluster IDs.

• resource_pools: resource-pool IDs.

• power_states: POWERED_ON, POWERED_OFF, or SUSPENDED.

List operations only return objects visible to the read-only account. The vCenter REST VM list has a maximum response size of 4,000 visible matching VMs.

Property allowlist

vsphere_query_properties cannot request arbitrary methods or properties. The default property allowlist is:

The object ID is normally obtained from one of the list tools. Example: first list VMs, then pass the returned vm-42 ID to vsphere_get_vm_summary.

Example Questions to Ask Your Coding Agent

Use the vSphere MCP tools and list all visible virtual machines.

Show only powered-on VMs and include their names and IDs.

List my vCenter datacenters, clusters, hosts, datastores, and networks.

Find the VM named payroll-api and show its detailed configuration.

Get the summary for VM vm-42 using the read-only vSphere tools.

Use only read-only vSphere tools. Do not call shell commands or other VMware APIs.

What Read-Only Means Here

There are three layers of protection:

1. The MCP server registers only nine approved read tools. There is no generic call_api tool.

2. Tool annotations mark every tool as read-only and non-destructive.

3. vCenter independently enforces the service account's Read-only role.

The server does make internal POST requests for login and API-release negotiation. These create temporary sessions or negotiate protocol details; they do not modify VMware inventory.

The server does not expose tools for:

• Creating, editing, cloning, relocating, registering, or deleting VMs.

• Powering VMs on, off, resetting, suspending, or rebooting them.

• Modifying tags, networks, datastores, hosts, clusters, or permissions.

• Connecting or disconnecting ESXi hosts.

• Calling arbitrary paths or HTTP methods.

MCP annotations are descriptive metadata, not a security boundary by themselves. The strict tool whitelist and vCenter permissions provide the actual enforcement.

Running Manually

Local stdio mode, used by coding agents:

.venv/bin/python -m vsphere_mcp --env-file .env --transport stdio

The process may appear to wait silently. That is normal: stdio mode waits for an MCP client.

Local Streamable HTTP mode:

.venv/bin/python -m vsphere_mcp \
  --env-file .env \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000

Endpoint:

http://127.0.0.1:8000/mcp

Local SSE mode:

.venv/bin/python -m vsphere_mcp \
  --env-file .env \
  --transport sse \
  --host 127.0.0.1 \
  --port 8000

Endpoint:

http://127.0.0.1:8000/sse

Sharing This Project

Sharing the code

Share the GitHub repository. Do not share .env.

Each person should:

1. Clone the repository.

2. Run scripts/bootstrap.py.

3. Enter their own read-only vCenter credentials locally.

4. Register the MCP server with their coding agent.

Sharing one central MCP server

A central server is possible, but it changes the security model:

• Put it behind HTTPS.

• Add bearer-token or OAuth authentication in a reverse proxy or gateway.

• Never expose the current HTTP/SSE server directly to the internet.

• Bind to 0.0.0.0 only when a secured proxy or private network is protecting it.

• Remember that every remote user sees whatever the central vCenter service account can see.

• Use separate server instances or delegated authentication when users require different vCenter permissions.

The current project does not implement remote-client authentication. Local stdio is therefore the recommended default.

Troubleshooting

HTTP 401 or "bad credentials"

Meaning: vCenter rejected the username or password.

Check:

• The username belongs to this vCenter.

• The password is correct and not expired.

• The account is not locked.

• The username includes the correct identity domain.

• The account supports non-interactive login instead of browser-only MFA.

HTTP 403 or "lacks read permission"

Meaning: authentication worked, but vCenter denied the operation.

Ask the VMware administrator to verify:

• Built-in Read-only role assignment.

• Correct inventory scope.

• Propagate to children is enabled when required.

• The account can read the datacenter, folder, cluster, host, datastore, network, and VM objects you expect.

Certificate verification failed

Meaning: Python does not trust the certificate presented by vCenter.

Ask for the company CA certificate chain and configure VSPHERE_CA_BUNDLE. Do not solve this in production by disabling verification.

Connection timeout or name-resolution error

Check:

• VPN is connected.

• The vCenter hostname opens from the same computer.

• DNS resolves the hostname.

• Firewall access to HTTPS port 443 is allowed.

• VSPHERE_HOST contains only the base vCenter address.

Codex cannot find the server

Run:

codex mcp get vsphere
codex mcp list

Then verify that:

• The configured Python path exists.

• The configured .env path exists.

• The repository was not moved after registration.

• Codex was restarted after setup.

Rerun vsphere-mcp-setup to repair the registration.

Tools are visible but return no inventory

The account may be valid but assigned to an empty or narrow inventory scope. Ask the administrator which objects the account is allowed to view.

VI/JSON tools report incompatibility

vsphere_get_vm_summary and vsphere_query_properties require vCenter 8.0 Update 1 or newer. The seven REST tools can still work with older supported vCenter versions.

Remove an incorrect manual override and let detection run again:

# VSPHERE_VI_JSON_RELEASE=

The repository was moved

Agent configurations contain absolute paths. Rerun the setup wizard after moving the repository.

Copy-Paste Prompt for Codex, Cursor, Claude, or Another Coding Agent

Copy this prompt into Codex, Cursor, Claude, or another coding agent:

Install the read-only vSphere MCP server from https://github.com/arjungowdal4601/vcenter_mcp.git.

Safety requirements:
- Never ask me to paste my vCenter password into this chat.
- Never print, log, commit, or display the contents of .env.
- Do not put vCenter credentials directly in Codex, Cursor, Claude, or MCP JSON/TOML configuration.
- Do not disable TLS certificate verification.
- Do not add any write, power, create, delete, clone, update, or generic API tools.

Installation steps:
1. Detect my operating system and confirm Git and Python 3.10 or newer are available.
2. Ask me where I want the repository installed. Do not ask for VMware credentials in chat.
3. Clone https://github.com/arjungowdal4601/vcenter_mcp.git into that location.
4. On macOS/Linux run: python3 scripts/bootstrap.py
   On Windows run: py scripts\bootstrap.py
5. Launch the setup wizard in an interactive terminal. Let the wizard collect the vCenter address, username, hidden password, and optional CA certificate locally.
6. Wait for the wizard to verify vCenter access and create .env.
7. If the active agent is Codex, let the wizard register the server globally and verify it with `codex mcp get vsphere`.
8. If the active agent is Cursor or Claude Code, use the README's stdio configuration with absolute paths. Reference .env through `--env-file`; do not copy its values into agent configuration.
9. Run the repository test suite.
10. Report the installation path, configured agent, MCP connection status, and test result. Do not report any secret values.

If an interactive hidden-password prompt is unavailable, create .env from .env.example and ask me to edit that local file myself. Do not ask me to send the password through chat.

Updating and Removing

Update the code:

git pull
.venv/bin/python -m pip install -e .

Windows:

git pull
.\.venv\Scripts\python.exe -m pip install -e .

Remove the Codex registration:

codex mcp remove vsphere

Deleting the repository also deletes the local .env and virtual environment. Remove the agent registration first so it does not retain broken paths.

Development and Tests

Install development dependencies:

python -m pip install -e ".[dev]"

Run tests:

pytest -q

The tests use mocked vCenter responses. They verify:

• The exact nine-tool read-only contract.

• REST and VI/JSON login flows.

• Session refresh behavior.

• Input and property allowlists.

• Automatic VI/JSON release negotiation.

• .env precedence and secret-safe writing.

• Guided setup behavior.

• Credential-free Codex registration.

A final production check must still be performed against a non-production vCenter using a dedicated Read-only account.

Official References

• vSphere Automation API

• REST session creation

• VI/JSON API

• vCenter API release negotiation

• vSphere Web Services API

• vSphere Automation SDK repositories

• Codex MCP documentation

• Cursor MCP documentation

• Claude Code MCP documentation