mjrestivo16/mcp-proxmox

Proxmox MCP Server

Model Context Protocol (MCP) server for Proxmox Virtual Environment management. Provides 35 comprehensive tools for managing VMs, containers, storage, backups, and cluster operations through the Proxmox VE API.

Features

Cluster & Node Management (4 tools)

• pve_get_cluster_status - Get Proxmox cluster status and health
• pve_list_nodes - List all nodes in the cluster
• pve_get_node_status - Get detailed status of a specific node
• pve_get_node_resources - Get CPU, memory, and storage usage for a node

Virtual Machine Management (11 tools)

• pve_list_vms - List all VMs across the cluster or on a specific node
• pve_get_vm_status - Get detailed status of a specific VM
• pve_get_vm_config - Get configuration of a specific VM
• pve_start_vm - Start a VM
• pve_stop_vm - Stop a VM (graceful shutdown or forced)
• pve_reboot_vm - Reboot a VM
• pve_suspend_vm - Suspend a VM
• pve_resume_vm - Resume a suspended VM
• pve_clone_vm - Clone a VM (full or linked)
• pve_delete_vm - Delete a VM (use with caution!)
• pve_migrate_vm - Migrate VM to another node (live or offline)

Container (LXC) Management (4 tools)

• pve_list_containers - List all LXC containers
• pve_get_container_status - Get status of a container
• pve_start_container - Start a container
• pve_stop_container - Stop a container

Storage Management (2 tools)

• pve_list_storage - List all storage pools
• pve_get_storage_content - List content of a storage pool (images, ISOs, backups, etc.)

Backup Management (2 tools)

• pve_list_backups - List backups for a VM or container
• pve_create_backup - Create a backup of a VM or container

Snapshot Management (4 tools)

• pve_list_snapshots - List snapshots of a VM
• pve_create_snapshot - Create a snapshot of a VM
• pve_rollback_snapshot - Rollback VM to a snapshot
• pve_delete_snapshot - Delete a snapshot

Task Management (2 tools)

• pve_list_tasks - List recent tasks on a node
• pve_get_task_status - Get status of a specific task

Network Management (1 tool)

• pve_list_networks - List network interfaces on a node

Terraform Integration (2 tools)

• pve_generate_terraform - Generate Terraform configuration for a VM
• pve_generate_terraform_provider - Generate Terraform provider configuration for the cluster

Installation

npm install
npm run build

Configuration

The server requires Proxmox VE API credentials configured via environment variables. Two authentication methods are supported:

API Token Authentication (Recommended)

export PROXMOX_URL="https://your-proxmox-host:8006"
export PROXMOX_USER="root@pam"
export PROXMOX_TOKEN_ID="your-token-id"
export PROXMOX_TOKEN_SECRET="your-token-secret"

To create an API token in Proxmox:

1. Log into Proxmox web UI
2. Go to Datacenter > Permissions > API Tokens
3. Click "Add" to create a new token
4. Uncheck "Privilege Separation" for full access
5. Save the token ID and secret

Password Authentication (Alternative)

export PROXMOX_URL="https://your-proxmox-host:8006"
export PROXMOX_USER="root@pam"
export PROXMOX_PASSWORD="your-password"

Usage with Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/path/to/mcp-proxmox/dist/index.js"],
      "env": {
        "PROXMOX_URL": "https://your-proxmox-host:8006",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_ID": "your-token-id",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Development

Run in development mode with hot reload:

npm run dev

Security Notes

• The server accepts self-signed SSL certificates by default (common for Proxmox installations)
• For production use, consider using properly signed certificates
• API tokens are more secure than password authentication
• Ensure proper access controls on the Proxmox user/token

Example Use Cases

1. VM Lifecycle Management: Start, stop, reboot VMs across your cluster
2. Resource Monitoring: Check CPU, memory, storage usage on nodes
3. Backup Operations: Create and manage VM/container backups
4. Snapshot Management: Create snapshots before changes, rollback if needed
5. Live Migration: Move VMs between nodes for maintenance
6. Infrastructure as Code: Export VM configurations as Terraform

API Reference

All tools return JSON responses from the Proxmox API. The server handles authentication, error handling, and response formatting automatically.

For detailed Proxmox API documentation, see: https://pve.proxmox.com/pve-docs/api-viewer/

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.