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.

Overview
Key Features
Architecture
Directory Structure
Installation
Configuration
Running the Server
Available Tools / API
Error Handling
Audit Logging
Rate Limiting
Security Model
Development
Docker Usage
Troubleshooting
Changelog
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

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 for version history and changes.

License

This project is licensed under the MIT License. See LICENSE for details.

vSphere-MCP-Pro

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

Overview
Key Features
Architecture
Directory Structure
Installation
Configuration
Running the Server
Available Tools / API
Error Handling
Audit Logging
Rate Limiting
Security Model
Development
Docker Usage
Troubleshooting
Changelog
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

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 for version history and changes.

License

This project is licensed under the MIT License. See LICENSE for details.

vSphere-MCP-Pro

vSphere-MCP-Pro

Table of Contents

Overview

Key Features

✔ Secure by design

✔ Strong authorization model

✔ Operationally robust

✔ High performance

Architecture

Directory Structure

Installation

Prerequisites

Install from source

Configuration

Required Environment Variables

Optional Environment Variables

Example Configuration

Running the Server

Local execution

Available Tools / API

VM Discovery

Inventory Discovery

Power Operations

Snapshot Operations

Destructive Operations (require confirm=True)

Error Handling

Audit Logging

Rate Limiting

Security Model

Development

Install dev deps

Run with autoreload

Docker Usage

Build

Run

Troubleshooting

"login failed: HTTP 401"

"Hostname not in allowed set"

Rate limit errors

SSL certificate issues

VsphereApiError exceptions

Changelog

License

vSphere-MCP-Pro

Table of Contents

Overview

Key Features

✔ Secure by design

✔ Strong authorization model

✔ Operationally robust

✔ High performance

Architecture

Directory Structure

Installation

Prerequisites

Install from source

Configuration

Required Environment Variables

Optional Environment Variables

Example Configuration

Running the Server

Local execution

Available Tools / API

VM Discovery

Inventory Discovery

Power Operations

Snapshot Operations

Destructive Operations (require confirm=True)

Error Handling

Audit Logging

Rate Limiting

Security Model

Development

Install dev deps

Run with autoreload

Docker Usage

Build

Run

Troubleshooting

Destructive Operations (require `confirm=True`)

Destructive Operations (require `confirm=True`)