VSphere MCP Pro

vSphere-MCP-Pro

A secure, feature-rich Model Context Protocol (MCP) server for VMware vCenter 8.0+.

Exposes controlled vCenter operations via MCP tools including VM lifecycle management, snapshot operations, datastore/host discovery, and more—with audit logging, RBAC authorization, session pooling, and rate limiting.

---

Table of Contents

• [Overview](#overview)
• [Key Features](#key-features)
• [Architecture](#architecture)
• [Directory Structure](#directory-structure)
• [Installation](#installation)
• [Configuration](#configuration)
• [Running the Server](#running-the-server)
• [Available Tools / API](#available-tools--api)
• [Error Handling](#error-handling)
• [Audit Logging](#audit-logging)
• [Rate Limiting](#rate-limiting)
• [Security Model](#security-model)
• [Development](#development)
• [Docker Usage](#docker-usage)
• [Troubleshooting](#troubleshooting)
• [Changelog](#changelog)
• [License](#license)

---

Overview

vsphere-mcp-pro is an MCP server designed for VMware vCenter 8.0+ environments.

It provides:

• Safe, structured access to vCenter operations
• Strict authorization via roles → allowed tools
• Snapshot + VM lifecycle operations
• Auditing and rate limiting for secure multi-tenant use
• Support for both /api (preferred) and /rest vCenter endpoints
• Optional host allow-listing to prevent accidental cross-cluster operations
• Connection pooling to prevent vCenter session exhaustion

The server runs using FastMCP and automatically wraps every tool operation with:

• Token-based RBAC (Authorizer)
• Token bucket rate limiting
• JSONL audit logging
• Confirmation requirement for destructive operations
• Proper error handling with detailed vCenter error context

---

Key Features

✔ Secure by design

• SSL verification enabled by default
• Optional CA bundle support
• Allowed-host enforcement prevents unauthorized vCenter targets

✔ Strong authorization model

• Token → role mapping
• Role → allowed-tools mapping
• Enforced unless explicitly disabled
• Destructive operations require confirm=True

✔ Operationally robust

• Automatic retry logic for vCenter API calls (Retry + HTTPAdapter)
• Session auto-renewal on 401
• Connection pooling with automatic cleanup
• Proper session logout on shutdown
• Extensive logging for auditing and observability
• Rich error messages with vCenter error context

✔ High performance

• Thread-safe vCenter session pooling (one session per host)
• Eliminates per-request authentication overhead
• MCP server built with uvicorn

---

Architecture

Key modules:

• server.py

Builds the MCP server, registers all tools, injects authorization, rate-limiting, session pool, and auditing wrappers.

• vsphere_client.py

Handles retries, authentication, session pooling, and REST/API mode switching for VMware vCenter. Includes:

• VsphereClient - Thread-safe vCenter REST API client
• VsphereClientPool - Connection pool with automatic cleanup
• VsphereApiError - Rich exception class for API errors

• authz.py

Implements:

• Token → role resolution
• Role → tool gating
• Token bucket rate limiting

• audit.py

Writes JSON-lines logs for every operation.

• config.py

Loads environment variables into a typed AppConfig using pydantic.

---

Directory Structure

/
├── vsphere_mcp_pro/          # Python package
│   ├── __init__.py
│   ├── server.py             # MCP server and tool definitions
│   ├── vsphere_client.py     # vCenter client, pool, and exceptions
│   ├── authz.py              # Authorization and rate limiting
│   ├── audit.py              # Audit logging
│   └── config.py             # Configuration loading
├── pyproject.toml            # Project metadata and dependencies
├── README.md
├── CHANGELOG.md
├── LICENSE
├── env.example               # Example environment configuration
└── Dockerfile

---

Installation

Prerequisites

• Python 3.10+
• VMware vCenter 8.0+
• Valid API credentials

Install from source

git clone https://github.com/Warezloder/vSphere-MCP-Pro
cd vSphere-MCP-Pro
pip install -e .

---

Configuration

Configuration is environment-driven. Copy the example file:

cp env.example .env

Required Environment Variables

| Variable | Description | | ----------------------- | --------------------------------------------- | | VCENTER_HOST | vCenter hostname/IP | | VCENTER_USER | vCenter username | | VCENTER_PASSWORD | vCenter password | | ROLES_TO_TOOLS | JSON map of role → allowed tools | | TOKENS_TO_ROLES | JSON map of token → role | | ALLOWED_VCENTER_HOSTS | Optional allowlist for multi-host deployments |

Optional Environment Variables

| Variable | Default | Description | | -------------------- | -------------------- | ------------------------------------ | | VSPHERE_API_MODE | api | API mode: api or rest | | INSECURE | false | Disable SSL verification | | VCENTER_CA_BUNDLE | | Path to custom CA bundle | | VCENTER_TIMEOUT_S | 20 | Request timeout in seconds | | VCENTER_RETRIES | 3 | Number of retry attempts | | VCENTER_BACKOFF | 0.5 | Retry backoff factor | | SERVER_HOST | 0.0.0.0 | Server bind address | | SERVER_PORT | 8000 | Server port | | MCP_PATH | /mcp | MCP endpoint path | | AUDIT_LOG_PATH | | Audit log file (blank = stdout) | | AUTH_ENFORCE | true | Enforce RBAC | | RATE_LIMIT | true | Enable rate limiting | | RATE_LIMIT_RPS | 5 | Requests per second | | RATE_LIMIT_BURST | 10 | Burst allowance |

Example Configuration

VCENTER_HOST=vcenter.example.com
VCENTER_USER=administrator@vsphere.local
VCENTER_PASSWORD=s3cret
TOKENS_TO_ROLES={"token1": "read", "token2": "ops", "token3": "admin"}
ROLES_TO_TOOLS={"read":["list_vms","get_vm_details"],"ops":["power_on_vm","power_off_vm"],"admin":["delete_vm"]}

---

Running the Server

Local execution

python -m vsphere_mcp_pro.server

Server defaults (override via env vars):

• Host: 0.0.0.0
• Port: 8000
• MCP path: /mcp

---

Available Tools / API

Below is a categorized summary of available MCP tools exposed by the server.

VM Discovery

| Tool | Description | | ----------------- | --------------------- | | list_vms | List all VMs | | get_vm_details | Get VM details by ID |

Inventory Discovery

| Tool | Description | | -------------------------------- | ------------------------------ | | list_hosts | List ESXi hosts | | list_datastores | List datastores | | list_networks | List networks | | list_datacenters | List datacenters | | get_datastore_usage | Get datastore capacity/usage | | get_resource_utilization_summary | Summary of all resources |

Power Operations

| Tool | Description | | -------------- | ---------------- | | power_on_vm | Power on a VM | | power_off_vm | Power off a VM | | restart_vm | Restart a VM |

Snapshot Operations

| Tool | Description | | -------------------- | ---------------------------------------- | | list_vm_snapshots | List snapshots for a VM | | create_vm_snapshot | Create a snapshot | | delete_vm_snapshot | Delete a snapshot (requires confirm) |

Destructive Operations (require confirm=True)

| Tool | Description | | --------------------- | ---------------------------------- | | delete_vm | Permanently delete a VM | | delete_vm_snapshot | Delete a snapshot | | modify_vm_resources | Modify CPU/memory (requires power off) |

---

Error Handling

The server provides rich error context via the VsphereApiError exception:

VsphereApiError: Failed to get VM 'vm-999': HTTP 404 on /api/vcenter/vm/vm-999 [NOT_FOUND]: The VM was not found.

Error responses include:

• HTTP status code
• API path
• vCenter error type (e.g., NOT_FOUND, ALREADY_EXISTS)
• Human-readable error messages from vCenter

The exception provides convenience properties:

• is_not_found - 404 or NOT_FOUND error
• is_unauthorized - 401 error
• is_forbidden - 403 error
• is_conflict - 409 error

---

Audit Logging

Every MCP tool call is logged as a JSON line containing:

• Tool name
• Execution status (ok/error)
• Duration (ms)
• Sanitized arguments (passwords & tokens masked)
• Error message (if any)
• Role + host context

Logs write to stdout by default, or to AUDIT_LOG_PATH if configured.

---

Rate Limiting

Uses a token-bucket strategy:

• Configurable RATE_LIMIT_RPS and RATE_LIMIT_BURST
• Separate buckets per token
• Disabled by setting RATE_LIMIT=false

---

Security Model

| Mechanism | Purpose | | ---------------------- | ----------------------------------------- | | SSL verification | Prevent MITM attacks | | Allowed-host list | Prevent unauthorized target selection | | Role → tool mapping | Enforce least-privilege principle | | Token authentication | Multi-tenant safe access | | Required confirmations | Prevent accidental destructive operations | | Rate limiting | Protects vCenter and MCP server | | Session pooling | Prevents vCenter session exhaustion |

---

Development

Install dev deps

pip install -e .[dev]

Run with autoreload

uvicorn vsphere_mcp_pro.server:main --reload

---

Docker Usage

Build

docker build -t vsphere-mcp-pro .

Run

docker run \
  --rm \
  -p 8000:8000 \
  --env-file .env \
  vsphere-mcp-pro

---

Troubleshooting

"login failed: HTTP 401"

• Verify vCenter username/password
• Ensure correct API mode (VSPHERE_API_MODE=api|rest)

"Hostname not in allowed set"

• Add the hostname to ALLOWED_VCENTER_HOSTS

Rate limit errors

• Increase RATE_LIMIT_BURST
• Adjust per-token usage

SSL certificate issues

• Set VCENTER_CA_BUNDLE to your CA bundle path
• Or disable SSL verification (not recommended): INSECURE=true

VsphereApiError exceptions

• Check the error message for vCenter-specific details
• Use error.is_not_found, error.is_forbidden, etc. for programmatic handling
• Verify the VM/resource ID exists

---

Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

---

License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Warezloder
• Source: Warezloder/vSphere-MCP-Pro
• License: MIT
• Homepage: https://github.com/Warezloder/vSphere-MCP-Pro

Install and usage instructions live in the source repository linked above.