Proxmox MCP Enhanced 🚀

115 Specialized Tools for Comprehensive Proxmox VE Management via Model Context Protocol

Overview

Proxmox MCP Enhanced provides a complete Model Context Protocol (MCP) server implementation for managing Proxmox Virtual Environment (VE) infrastructure. With 115 specialized tools covering every aspect of Proxmox administration, this server enables AI assistants and automation systems to perform complex virtualization tasks seamlessly.

Features

🎯 115 Specialized Tools

• VM Management (9 tools): Create, start, stop, restart, suspend, resume, migrate, clone, delete
• Container Management (9 tools): Full LXC container lifecycle
• Storage Management (10 tools): Create, delete, enable, disable, list, scan, prune, allocate, upload, download
• Cluster Management (8 tools): Node management, quorum, resources
• Monitoring (2 tools): Metrics, alerts, logs, performance
• Backup & Recovery (8 tools): Automated backups, restore, scheduling
• Networking (6 tools): Bridges, bonds, VLANs, DNS configuration
• High Availability (6 tools): HA groups, resource management, failover
• Firewall (5 tools): Rules, groups, aliases, security policies
• User Management (3 tools): Users, groups, roles, permissions, tokens
• API & Resources (1 tool): Task management, resource queries
• Templates (4 tools): VM/container template management
• Migration (3 tools): Live migration, storage migration
• Snapshots (4 tools): Create, restore, manage, delete
• Replication (3 tools): Configure and manage replication
• Ceph Storage (5 tools): Pool creation, OSD management, monitors, status, CRUSH rules
• ZFS Storage (4 tools): Pool creation, dataset management, snapshots, scrubbing
• SDN/VXLAN (4 tools): Software-defined networking zones, virtual networks, subnets
• Automation (3 tools): Create tasks, schedule automation, check status
• Reporting (3 tools): Generate reports, schedule reports, export data
• ISO Management (4 tools) 🆕: Dynamic ISO discovery, download, upload, listing

🔐 Security First

• TypedDict Type Safety: Every parameter strictly typed, no Dict[str, Any]
• Token & Password Authentication: Support for both authentication methods
• SSL/TLS Support: Secure communication with certificate verification
• Permission Management: Fine-grained access control integration

⚡ Modern Architecture

• Async/Await: Full asynchronous operation for optimal performance
• Connection Pooling: Efficient resource management
• MCP Protocol: Native Model Context Protocol implementation
• Modular Design: Clean separation of concerns

Installation

Via pip

pip install proxmox-mcp-enhanced

From source

git clone https://github.com/yourusername/proxmox-mcp-enhanced.git
cd proxmox-mcp-enhanced
pip install -e .

Configuration

Environment Variables

Create a .env file or set these environment variables:

# Required - Host configuration
PROXMOX_HOST=your-proxmox-host.example.com
PROXMOX_USER=root@pam

# Authentication (choose one method)
# Option 1: API Token (recommended)
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-value

# Option 2: Password
PROXMOX_PASSWORD=your-password

# Optional settings
PROXMOX_PORT=8006              # Default: 8006
PROXMOX_VERIFY_SSL=true        # Default: true

MCP Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "proxmox": {
      "command": "proxmox-mcp",
      "env": {
        "PROXMOX_HOST": "your-host",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "token-name",
        "PROXMOX_TOKEN_VALUE": "token-value"
      }
    }
  }
}

Usage Examples

Basic VM Operations

# Create a new VM
{
  "tool": "vm_create",
  "arguments": {
    "vmid": 100,
    "node": "pve-node1",
    "name": "test-vm",
    "memory": 2048,
    "cores": 2,
    "storage": "local-lvm",
    "disk_size": "10G"
  }
}

# Start the VM
{
  "tool": "vm_start",
  "arguments": {
    "vmid": 100,
    "node": "pve-node1"
  }
}

Container Management

# Create an LXC container
{
  "tool": "container_create",
  "arguments": {
    "vmid": 200,
    "node": "pve-node1",
    "ostemplate": "local:vztmpl/ubuntu-22.04-standard.tar.gz",
    "hostname": "test-container",
    "memory": 1024,
    "cores": 1,
    "rootfs": "local-lvm:8"
  }
}

Advanced Storage Operations

# Create a Ceph pool
{
  "tool": "ceph_pool_create",
  "arguments": {
    "name": "rbd-pool",
    "size": 3,
    "min_size": 2,
    "pg_num": 128
  }
}

# Create ZFS dataset
{
  "tool": "zfs_dataset_create",
  "arguments": {
    "name": "tank/datasets/test",
    "pool": "tank",
    "compression": "lz4",
    "dedup": "off"
  }
}

SDN/VXLAN Configuration

# Create VXLAN zone
{
  "tool": "sdn_zone_create",
  "arguments": {
    "zone": "vxlan-zone",
    "type": "vxlan",
    "peers": ["10.0.0.1", "10.0.0.2"],
    "mtu": 1450
  }
}

ISO Management 🆕

# Search for OS ISOs dynamically
{
  "tool": "iso_search",
  "arguments": {
    "os_name": "ubuntu",
    "version": "22.04",
    "variant": "server",
    "architecture": "amd64"
  }
}

# Download ISO directly to Proxmox node
{
  "tool": "iso_download_direct",
  "arguments": {
    "url": "https://releases.ubuntu.com/22.04/ubuntu-22.04.5-live-server-amd64.iso",
    "filename": "ubuntu-22.04-server.iso",
    "node": "pve-node1",
    "checksum_url": "https://releases.ubuntu.com/22.04/SHA256SUMS"
  }
}

# List available ISOs
{
  "tool": "iso_list_available",
  "arguments": {
    "storage": "local"
  }
}

For complete ISO download documentation, see ISO_DOWNLOAD_GUIDE.md.

Automation & Reporting

# Schedule automated backups
{
  "tool": "schedule_create",
  "arguments": {
    "name": "daily-backup",
    "schedule": "0 2 * * *",
    "command": "backup:all",
    "node": "pve-node1"
  }
}

# Generate performance report
{
  "tool": "performance_report",
  "arguments": {
    "analysis_type": "bottleneck",
    "metrics": ["cpu", "memory", "disk", "network"],
    "recommendations": true
  }
}

Tool Categories

Core Infrastructure (41 tools)

• VM Management: 9 tools
• Container Management: 9 tools
• Storage Management: 10 tools
• Ceph Storage: 5 tools
• ZFS Storage: 4 tools
• Cluster Management: 8 tools

Operations & Monitoring (23 tools)

• Monitoring: 2 tools
• Backup Management: 8 tools
• Network Management: 6 tools
• High Availability: 6 tools

Security & Access (15 tools)

• Firewall Management: 5 tools
• User Management: 3 tools
• API/Resource Tools: 1 tool
• Token Management: Included in user tools

Advanced Features (22 tools)

• Templates: 4 tools
• Migration: 3 tools
• Snapshots: 4 tools
• Replication: 3 tools
• SDN/VXLAN: 4 tools
• Automation: 3 tools
• Reporting: 3 tools

Architecture

Project Structure

proxmox-mcp-enhanced/
├── src/
│   └── proxmox_mcp/
│       ├── __init__.py          # Tool registration (115 tools)
│       ├── base.py              # Base ToolHandler class
│       ├── types.py             # TypedDict definitions
│       ├── server.py            # MCP server implementation
│       ├── api/
│       │   ├── __init__.py
│       │   └── client.py        # Proxmox API client
│       └── tools/
│           ├── vm_tools.py      # VM management
│           ├── container_tools_complete.py
│           ├── storage_tools_complete.py
│           ├── ceph_tools.py
│           ├── zfs_tools.py
│           └── ... (15 more tool modules)
├── tests/
├── pyproject.toml
└── README.md

Type Safety

All tools use strict TypedDict definitions:

class VMCreateArgs(TypedDict):
    vmid: int
    node: str
    name: str
    memory: Optional[int]
    cores: Optional[int]
    # ... no Dict[str, Any]!

Development

Running Tests

pytest tests/
pytest --cov=proxmox_mcp tests/

Code Quality

# Format code
black src/

# Type checking
mypy src/

# Linting
ruff src/

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/new-tool)
3. Implement with TypedDict (no Dict[str, Any])
4. Add tests
5. Commit (feat: Add new amazing tool)
6. Push and create PR

Roadmap

• [x] Complete implementation of all 115 tools (✅ Done!)
• [x] Dynamic ISO discovery and download (✅ Done!)
• [x] Full TypedDict type safety (✅ Done!)
• [x] Production-ready deployment (✅ Done!)
• [ ] Add comprehensive test suite
• [ ] Create interactive documentation
• [ ] Add tool chaining capabilities
• [ ] Implement batch operations
• [ ] Add prometheus metrics export
• [ ] Create terraform provider integration

License

MIT License - see LICENSE file for details.

Support

• 📧 Email: support@proxmox-mcp.dev
• 🐛 Issues: GitHub Issues
• 💬 Discord: Join our server
• 📖 Docs: Full Documentation

Acknowledgments

• Proxmox VE team for the excellent virtualization platform
• Anthropic for the Model Context Protocol specification
• All contributors and users of this project

---

Built with ❤️ for the Proxmox community