vSphere MCP Server

A VMware vSphere/ESXi integration MCP (Model Context Protocol) server built with Python's fastmcp library and pyVmomi. This server provides AI agents with tools for managing and monitoring VMware infrastructure.

Quick Start with Docker

Pull and Run

docker pull ghcr.io/presidio-federal/vsphere-mcp:latest

docker run -d \
  --name vsphere-mcp \
  -p 3012:3012 \
  -e VSPHERE_HOST=vcenter.example.com \
  -e VSPHERE_USERNAME=administrator@vsphere.local \
  -e VSPHERE_PASSWORD=your-password \
  -e DISABLE_JWT_AUTH=true \
  ghcr.io/leevanginkel/vsphere-mcp:latest

Docker Compose

version: '3.8'
services:
  vsphere-mcp:
    image: ghcr.io/leevanginkel/vsphere-mcp:latest
    container_name: vsphere-mcp
    ports:
      - "3012:3012"
    environment:
      - VSPHERE_HOST=vcenter.example.com
      - VSPHERE_USERNAME=administrator@vsphere.local
      - VSPHERE_PASSWORD=${VSPHERE_PASSWORD}
      - VSPHERE_PORT=443
      - VSPHERE_VERIFY_SSL=false
      - DISABLE_JWT_AUTH=true
    restart: unless-stopped

Available Tools

VM Management

Tool	Description	Parameters
vsphere_vm_get_info	Get detailed information about a specific virtual machine	vm_name or vm_id
vsphere_vm_list	List virtual machines with optional filters (default limit: 10)	datacenter, folder, power_state, limit
vsphere_vm_power_management	Manage VM power operations (power_on, power_off, suspend, reset, shutdown_guest, restart_guest)	operation, vm_name or vm_id
vsphere_vm_deploy_from_template	Deploy a new VM from Content Library template or clone from existing VM	vm_name, datastore_name, template_name, and many optional customization parameters

Content Library

Tool	Description	Parameters
vsphere_content_library_get_info	Get information about Content Libraries and their items	library_name, library_id, list_items, item_name
vsphere_content_library_template_info	Get detailed OVF/OVA template info including vApp properties	template_name, library_name, library_item_id

Host Management

Tool	Description	Parameters
vsphere_host_get_info	Get detailed information about a specific ESXi host	host_name or host_id
vsphere_host_list	List all ESXi hosts with optional filters	datacenter, cluster, connection_state

Resource Management

Tool	Description	Parameters
vsphere_cluster_get_info	Get detailed information about a vSphere cluster	cluster_name or cluster_id
vsphere_resource_pool_get_info	Get detailed information about a resource pool	pool_name or pool_id

Networking

Tool	Description	Parameters
vsphere_vswitch_get_info	Get information about virtual switches (standard and distributed)	host_name, vswitch_name
vsphere_portgroup_get_info	Get information about portgroups	host_name, portgroup_name

Monitoring

Tool	Description	Parameters
vsphere_performance_get_stats	Get performance statistics for VMs or hosts	entity_type (vm/host), entity_name, metrics
vsphere_health_check	Comprehensive health check of vSphere infrastructure	None

Environment Variables

Required (vSphere Connection)

Variable	Description
VSPHERE_HOST	vCenter or ESXi hostname/IP
VSPHERE_USERNAME	vSphere username
VSPHERE_PASSWORD	vSphere password

Optional

Variable	Default	Description
VSPHERE_PORT	443	vSphere API port
VSPHERE_VERIFY_SSL	false	Verify SSL certificates
TRANSPORT	streamable-http	Transport type (stdio, streamable-http)
PORT	3012	Server port
HOST	0.0.0.0	Server bind address
DISABLE_JWT_AUTH	false	Disable JWT authentication
AZURE_AD_TENANT_ID	-	Azure AD tenant ID (required if JWT enabled)
AZURE_AD_CLIENT_ID	-	Azure AD client ID (optional)

Local Development

Prerequisites

• Python 3.10 or higher
• pip (Python package installer)
• Access to a vSphere/ESXi environment

Setup

# Clone the repository
git clone https://github.com/Presidio-Federal/vsphere-mcp.git
cd vsphere-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install fastmcp[cli]

# Configure environment
cp .env.example .env  # Create from example if available
# Edit .env with your vSphere credentials

Running Locally

# Using FastMCP CLI (recommended)
fastmcp run server.py --transport http --port 3012

# Or directly with Python
python server.py

# STDIO transport (for MCP client testing)
fastmcp run server.py --transport stdio

Building the Container

# Build locally
docker build -t vsphere-mcp:local -f dockerfile .

# Run local build
docker run -d \
  --name vsphere-mcp \
  -p 3012:3012 \
  -e VSPHERE_HOST=vcenter.example.com \
  -e VSPHERE_USERNAME=administrator@vsphere.local \
  -e VSPHERE_PASSWORD=your-password \
  -e DISABLE_JWT_AUTH=true \
  vsphere-mcp:local

HTTP Headers (Alternative Credentials)

You can pass vSphere credentials via HTTP headers instead of environment variables:

Header	Description
X-vSphere-Host	vSphere hostname
X-vSphere-Username	vSphere username
X-vSphere-Password	vSphere password
X-vSphere-Port	vSphere port
X-vSphere-Verify-SSL	SSL verification (true/false)

Authentication

The server supports two authentication modes:

1. JWT Authentication (production): Validates Azure AD JWT tokens. Requires AZURE_AD_TENANT_ID.
2. No Authentication (development): Set DISABLE_JWT_AUTH=true

Project Structure

vsphere-mcp/
├── __init__.py              # Package initialization
├── __main__.py              # Entry point for module execution
├── server.py                # Main server implementation
├── utilities.py             # Utility functions (auth, credentials)
├── requirements.txt         # Python dependencies
├── dockerfile               # Container configuration
├── README.md                # This file
└── tools/                   # Tool implementations
    ├── vm_management/       # VM tools
    ├── content_library/     # Content Library tools
    ├── host_management/     # Host tools
    ├── resource_management/ # Cluster & Resource Pool tools
    ├── networking/          # vSwitch & Portgroup tools
    └── monitoring/          # Performance & Health tools

Troubleshooting

SSL Certificate Errors

Set VSPHERE_VERIFY_SSL=false in your environment variables.

Connection Timeouts

Ensure your vSphere host is accessible and firewall rules allow traffic on port 443.

Authentication Failures

• Verify vSphere credentials are correct
• Check user has appropriate vSphere permissions
• For JWT auth, ensure Azure AD configuration is correct

Security Notes

• Never commit credentials to version control
• Use environment variables or secure secret management
• Enable SSL verification in production environments
• Use JWT authentication in production deployments
• Regularly rotate vSphere credentials

License

MIT