vSphere MCP Server

MCP server for VMware vSphere infrastructure management. Provides comprehensive access to vSphere environments through the Model Context Protocol.

Features

• Seamless Authentication: Domain-based credential caching with GUI prompts

• VM Management: List, inspect, and control virtual machines

• Infrastructure Monitoring: Monitor hosts, datacenters, and datastores

• Network Discovery: Explore networks and extract VLAN information

• Organization Tools: Navigate folders and organizational structures

• Secure Credential Storage: macOS Keychain integration with TTL

Installation

From PyPI (Recommended)

pip install vsphere-mcp-server

From Source

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

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "vsphere": {
      "command": "python",
      "args": ["-m", "vsphere_mcp_server.server"]
    }
  }
}

Available Tools

Authentication

• vsphere_clear_credentials(hostname) - Clear cached credentials for domain

Virtual Machine Management

• list_vms(hostname) - List all VMs with basic info

• get_vm_details(hostname, vm_id) - Detailed VM configuration

• power_on_vm(hostname, vm_id) - Power on VM

• power_off_vm(hostname, vm_id) - Power off VM

Infrastructure Management

• list_hosts(hostname) - List ESXi hosts

• get_host_details(hostname, host_id) - Host details

• list_datacenters(hostname) - List datacenters

• get_datacenter_details(hostname, datacenter_id) - Datacenter details

• list_datastores(hostname) - List datastores with capacity

• get_datastore_details(hostname, datastore_id) - Datastore details

Organization

• list_folders(hostname, folder_type) - List folders by type

• get_folder_details(hostname, folder_id) - Folder details

Networking

• list_networks(hostname) - List networks with VLAN info

• get_network_details(hostname, network_id) - Network details

• list_vlans(hostname) - Extract VLAN info from network names

Usage Examples

Basic VM Operations

# List all virtual machines
list_vms("vcenter.domain.local")

# Get detailed VM information
get_vm_details("vcenter.domain.local", "vm-123")

# Power operations
power_on_vm("vcenter.domain.local", "vm-123")
power_off_vm("vcenter.domain.local", "vm-123")

Infrastructure Monitoring

# Check datastore capacity
list_datastores("vcenter.domain.local")

# Monitor host status
list_hosts("vcenter.domain.local")
get_host_details("vcenter.domain.local", "host-456")

Network Discovery

# Explore network configuration
list_networks("vcenter.domain.local")

# Extract VLAN information
list_vlans("vcenter.domain.local")

Credential Management

# Clear stored credentials if needed
vsphere_clear_credentials("vcenter.domain.local")

Authentication

The server uses domain-based credential caching:

1. First Use: GUI prompts for username and password

2. Credential Storage: Stored in macOS Keychain with 4-hour TTL

3. Automatic Renewal: Re-prompts when credentials expire

4. Domain Extraction: vcenter.domain.local → domain.local

Supported Username Formats

• username@domain.local

• domain\username (converted to @ format)

• username (domain auto-appended)

Security

• Credentials stored securely in macOS Keychain

• 4-hour TTL prevents stale credential usage

• SSL verification disabled by default (common in enterprise environments)

• Session tokens used for API authentication

• Automatic session cleanup on exit

Error Handling

The server provides clear error messages with troubleshooting steps:

• Authentication Errors: Suggests clearing credentials

• Connection Errors: Indicates network/hostname issues

• API Errors: Shows specific vSphere API responses

Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/ tests/
isort src/ tests/

# Type checking
mypy src/

Troubleshooting

Authentication Issues

1. Clear credentials: vsphere_clear_credentials("hostname")

2. Verify username format includes domain

3. Check network connectivity to vCenter

Connection Issues

1. Verify hostname is reachable

2. Check vCenter is running and accessible

3. Confirm SSL/TLS configuration

Permission Issues

1. Verify user has required vSphere permissions

2. Check role assignments in vCenter

3. Ensure user can access required objects

License

MIT License - see LICENSE file for details.