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

Installation

Prerequisites

• Python 3.10+

• VMware vCenter 8.0+

• Valid API credentials

Install from source

Configuration

Configuration is environment-driven. Copy the example file:

Required Environment Variables

Optional Environment Variables

Example Configuration

Running the Server

Local execution

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:

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

Run with autoreload

Docker Usage

Build

Run

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

License

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