Warezloder/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
• 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

Optional Environment Variables

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

Inventory Discovery

Power Operations

Snapshot Operations

Destructive Operations (require confirm=True)

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

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

License

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