damens_mcps proxmox-mcp.instructions.md

Path-Specific Instructions: Proxmox MCP Server

Path: proxmox-mcp/

Project Overview

The Proxmox MCP server provides virtualization platform management capabilities through the Model Context Protocol. It allows AI assistants to manage Proxmox VE (Virtual Environment) clusters, VMs, and containers.

Key Characteristics

• Architecture: Pure JSON-RPC (no MCP library)
• Transport: stdin/stdout JSON-RPC protocol
• Canonical Server: working_proxmox_server.py ONLY
• Configuration: JSON configuration file (config.json)
• Authentication: Ticket-based authentication

Critical Requirements

Server Implementation

• ONLY use working_proxmox_server.py as the canonical implementation
• DO NOT use or modify other server files (they exist for historical reasons)
• Server reads JSON-RPC from stdin, writes to stdout
• Use stderr for debugging: print(message, file=sys.stderr)
• Supports cluster and multi-node operations

VM and Container Operations

VM/Container operations are production-critical and can cause:

• Service interruption
• Data loss
• Resource exhaustion
• Network connectivity issues

ALWAYS:

• Validate VM/Container IDs (VMIDs)
• Check resource availability before creation
• Verify node has capacity
• Log all operations with details
• Implement safety checks for destructive operations

Dangerous Operations

These operations can cause significant problems:

• VM/CT deletion - Permanent data loss
• Snapshot deletion - Cannot recover data
• Resource allocation changes - Can affect performance
• Network configuration - Can break connectivity
• Cluster operations - Can affect entire infrastructure

Configuration

Configuration File Format

{
  "host": "192.168.1.50",
  "port": 8006,
  "username": "root@pam",
  "password": "your-password",
  "verify_ssl": false,
  "timeout": 30,
  "node": "pve-node1",
  "realm": "pam"
}

Configuration File Location

• Primary: config.json in proxmox-mcp/ directory
• Example: config.example.json (copy to config.json)
• NEVER commit config.json file
• Set permissions: chmod 600 config.json