vSphere-MCP-Pro

A secure, feature-rich Machine Control Plane (MCP) server for VMware vCenter 8.0+.
This service exposes a controlled set of vCenter operations via MCP tools, including VM lifecycle management, snapshot operations, datastore/host discovery, and more—wrapped with audit logging, RBAC authorization, and rate limiting.

---

Table of Contents

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

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

• Token-based RBAC (Authorizer)
• Token bucket rate limiting
• JSONL audit logging
• Optional confirmation for destructive operations

---

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
• Extensive logging for auditing and observability

✔ High performance

• Thread-safe vCenter session management
• MCP server built with uvicorn

---

Architecture

Key modules:

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

• vsphere_client.py
  Handles retries, authentication, and REST/API mode switching for VMware vCenter.

• 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
│   ├── server.py
│   ├── vsphere_client.py
│   ├── authz.py
│   ├── audit.py
│   ├── config.py
├── pyproject.toml
├── README.md
├── .env.example
├── Dockerfile

---

Installation

Prerequisites

• Python 3.10+
• VMware vCenter 8.0+
• A valid set of 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

Example snippet:

VCENTER_HOST=vcenter.example.com
VCENTER_USER=administrator@vsphere.local
VCENTER_PASSWORD=s3cret
TOKENS_TO_ROLES={"token1": "read", "token2": "ops"}
ROLES_TO_TOOLS={"read":["list_vms","get_vm_details"],"ops":["power_on_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

• list_vms
• get_vm_details

Inventory Discovery

• list_hosts
• list_datastores
• list_networks
• list_datacenters
• get_datastore_usage
• get_resource_utilization_summary

Power Operations

• power_on_vm
• power_off_vm
• restart_vm

Snapshot Operations

• list_vm_snapshots
• create_vm_snapshot
• delete_vm_snapshot

VM Resource Management

• modify_vm_resources (CPU / memory)

Destructive Operations (require confirm=True)

• delete_vm
• delete_vm_snapshot

---

Audit Logging

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

• tool name
• execution status
• duration (ms)
• sanitized arguments (passwords & tokens masked)
• optional error message
• role + host context

Logs either write to stdout or to the configured AUDIT_LOG_PATH.

---

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

---

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 or
• Disable SSL verification only if absolutely necessary: INSECURE=true

---

License

This project is licensed under your chosen repository license.