# Proxmox MCP Enhanced 🚀

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

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)]()
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green)]()
[![Tools](https://img.shields.io/badge/Tools-115-orange)]()
[![Status](https://img.shields.io/badge/Status-Production%20Ready-brightgreen)]()
[![License](https://img.shields.io/badge/License-MIT-yellow)]()

## 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

```bash
pip install proxmox-mcp-enhanced
```

### From source

```bash
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:

```bash
# 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:

```json
{
  "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

```python
# 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

```python
# 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

```python
# 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

```python
# 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 🆕

```python
# 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](ISO_DOWNLOAD_GUIDE.md).

### Automation & Reporting

```python
# 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:

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

## Development

### Running Tests

```bash
pytest tests/
pytest --cov=proxmox_mcp tests/
```

### Code Quality

```bash
# 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](LICENSE) file for details.

## Support

- 📧 Email: support@proxmox-mcp.dev
- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/proxmox-mcp-enhanced/issues)
- 💬 Discord: [Join our server](https://discord.gg/proxmox-mcp)
- 📖 Docs: [Full Documentation](https://proxmox-mcp-enhanced.readthedocs.io)

## 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**