{"id":"7b7be5f2-56cc-4dc0-b2c0-1611698253e9","slug":"canvrno-proxmoxmcp","kind":"mcp","name":"ProxmoxMCP","summary":"MCP for Proxmox integration in Cline","owner":"canvrno","repoUrl":"https://github.com/canvrno/ProxmoxMCP","license":"MIT","licenseTier":"permissive","trust":"community","stars":297,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-02-19T03:31:12.000Z","addedAt":"2026-10-14T05:34:09.921Z","logoUrl":"https://avatars.githubusercontent.com/u/46584286?u=a64380b80b47b9a20073f103591141124743cd86&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T13:06:10.915Z","sample":false,"url":"https://conduits.dev/tools/canvrno-proxmoxmcp","language":"Python","transports":["stdio"],"install":{"pypi":"proxmox-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# 🚀 Proxmox Manager - Proxmox MCP Server\n\n![ProxmoxMCP](https://github.com/user-attachments/assets/e32ab79f-be8a-420c-ab2d-475612150534)\n\nA Python-based Model Context Protocol (MCP) server for interacting with Proxmox hypervisors, providing a clean interface for managing nodes, VMs, and containers.\n\n## 🏗️ Built With\n\n- [Cline](https://github.com/cline/cline) - Autonomous coding agent - Go faster with Cline.\n- [Proxmoxer](https://github.com/proxmoxer/proxmoxer) - Python wrapper for Proxmox API\n- [MCP SDK](https://github.com/modelcontextprotocol/sdk) - Model Context Protocol SDK\n- [Pydantic](https://docs.pydantic.dev/) - Data validation using Python type annotations\n\n## ✨ Features\n\n- 🤖 Full integration with Cline\n- 🛠️ Built with the official MCP SDK\n- 🔒 Secure token-based authentication with Proxmox\n- 🖥️ Tools for managing nodes and VMs\n- 💻 VM console command execution\n- 📝 Configurable logging system\n- ✅ Type-safe implementation with Pydantic\n- 🎨 Rich output formatting with customizable themes\n\n\n\nhttps://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b\n\n\n\n## 📦 Installation\n\n### Prerequisites\n- UV package manager (recommended)\n- Python 3.10 or higher\n- Git\n- Access to a Proxmox server with API token credentials\n\nBefore starting, ensure you have:\n- [ ] Proxmox server hostname or IP\n- [ ] Proxmox API token (see [API Token Setup](#proxmox-api-token-setup))\n- [ ] UV installed (`pip install uv`)\n\n### Option 1: Quick Install (Recommended)\n\n1. Clone and set up environment:\n   ```bash\n   # Clone repository\n   cd ~/Documents/Cline/MCP  # For Cline users\n   # OR\n   cd your/preferred/directory  # For manual installation\n   \n   git clone https://github.com/canvrno/ProxmoxMCP.git\n   cd ProxmoxMCP\n\n   # Create and activate virtual environment\n   uv venv\n   source .venv/bin/activate  # Linux/macOS\n   # OR\n   .\\.venv\\Scripts\\Activate.ps1  # Windows\n   ```\n\n2. Install dependencies:\n   ```bash\n   # Install with development dependencies\n   uv pip install -e \".[dev]\"\n   ```\n\n3. Create configuration:\n   ```bash\n   # Create config directory and copy template\n   mkdir -p proxmox-config\n   cp config/config.example.json proxmox-config/config.json\n   ```\n\n4. Edit `proxmox-config/config.json`:\n   ```json\n   {\n       \"proxmox\": {\n           \"host\": \"PROXMOX_HOST\",        # Required: Your Proxmox server address\n           \"port\": 8006,                  # Optional: Default is 8006\n           \"verify_ssl\": false,           # Optional: Set false for self-signed certs\n           \"service\": \"PVE\"               # Optional: Default is PVE\n       },\n       \"auth\": {\n           \"user\": \"USER@pve\",            # Required: Your Proxmox username\n           \"token_name\": \"TOKEN_NAME\",    # Required: API token ID\n           \"token_value\": \"TOKEN_VALUE\"   # Required: API token value\n       },\n       \"logging\": {\n           \"level\": \"INFO\",               # Optional: DEBUG for more detail\n           \"format\": \"%(asctime)s - %(name)s - %(levelname)s - %(message)s\",\n           \"file\": \"proxmox_mcp.log\"      # Optional: Log to file\n       }\n   }\n   ```\n\n### Verifying Installation\n\n1. Check Python environment:\n   ```bash\n   python -c \"import proxmox_mcp; print('Installation OK')\"\n   ```\n\n2. Run the tests:\n   ```bash\n   pytest\n   ```\n\n3. Verify configuration:\n   ```bash\n   # Linux/macOS\n   PROXMOX_MCP_CONFIG=\"proxmox-config/config.json\" python -m proxmox_mcp.server\n\n   # Windows (PowerShell)\n   $env:PROXMOX_MCP_CONFIG=\"proxmox-config\\config.json\"; python -m proxmox_mcp.server\n   ```\n\n   You should see either:\n   - A successful connection to your Proxmox server\n   - Or a connection error (if Proxmox details are incorrect)\n\n## ⚙️ Configuration\n\n### Proxmox API Token Setup\n1. Log into your Proxmox web interface\n2. Navigate to Datacenter -> Permissions -> API Tokens\n3. Create a new API token:\n   - Select a user (e.g., root@pam)\n   - Enter a token ID (e.g., \"mcp-token\")\n   - Uncheck \"Privilege Separation\" if you want full access\n   - Save and copy both the token ID and secret\n\n\n## 🚀 Running the Server\n\n### Development Mode\nFor testing and development:\n```bash\n# Activate virtual environment first\nsource .venv/bin/activate  # Linux/macOS\n# OR\n.\\.venv\\Scripts\\Activate.ps1  # Windows\n\n# Run the server\npython -m proxmox_mcp.server\n```\n\n### Cline Desktop Integration\n\nFor Cline users, add this configuration to your MCP settings file (typically at `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):\n\n```json\n{\n    \"mcpServers\": {\n        \"github.com/canvrno/ProxmoxMCP\": {\n            \"command\": \"/absolute/path/to/ProxmoxMCP/.venv/bin/python\",\n            \"args\": [\"-m\", \"proxmox_mcp.server\"],\n            \"cwd\": \"/absolute/path/to/ProxmoxMCP\",\n            \"env\": {\n                \"PYTHONPATH\": \"/absolute/path/to/ProxmoxMCP/src\",\n                \"PROXMOX_MCP_CONFIG\": \"/absolute/path/to/ProxmoxMCP/proxmox-config/config.json\",\n                \"PROXMOX_HOST\": \"your-proxmox-host\",\n                \"PROXMOX_USER\": \"username@pve\",\n                \"PROXMOX_TOKEN_NAME\": \"token-name\",\n                \"PROXMOX_TOKEN_VALUE\": \"token-value\",\n                \"PROXMOX_PORT\": \"8006\",\n                \"PROXMOX_VERIFY_SSL\": \"false\",\n                \"PROXMOX_SERVICE\": \"PVE\",\n                \"LOG_LEVEL\": \"DEBUG\"\n            },\n            \"disabled\": false,\n            \"autoApprove\": []\n        }\n    }\n}\n```\n\nTo help generate the correct paths, you can use this command:\n```bash\n# This will print the MCP settings with your absolute paths filled in\npython -c \"import os; print(f'''{{\n    \\\"mcpServers\\\": {{\n        \\\"github.com/canvrno/ProxmoxMCP\\\": {{\n            \\\"command\\\": \\\"{os.path.abspath('.venv/bin/python')}\\\",\n            \\\"args\\\": [\\\"-m\\\", \\\"proxmox_mcp.server\\\"],\n            \\\"cwd\\\": \\\"{os.getcwd()}\\\",\n            \\\"env\\\": {{\n                \\\"PYTHONPATH\\\": \\\"{os.path.abspath('src')}\\\",\n                \\\"PROXMOX_MCP_CONFIG\\\": \\\"{os.path.abspath('proxmox-config/config.json')}\\\",\n                ...\n            }}\n        }}\n    }}\n}}''')\"\n```\n\nImportant:\n- All paths must be absolute\n- The Python interpreter must be from your virtual environment\n- The PYTHONPATH must point to the src directory\n- Restart VSCode after updating MCP settings\n\n# 🔧 Available Tools\n\nThe server provides the following MCP tools for interacting with Proxmox:\n\n### get_nodes\nLists all nodes in the Proxmox cluster.\n\n- Parameters: None\n- Example Response:\n  ```\n  🖥️ Proxmox Nodes\n\n  🖥️ pve-compute-01\n    • Status: ONLINE\n    • Uptime: ⏳ 156d 12h\n    • CPU Cores: 64\n    • Memory: 186.5 GB / 512.0 GB (36.4%)\n\n  🖥️ pve-compute-02\n    • Status: ONLINE\n    • Uptime: ⏳ 156d 11h\n    • CPU Cores: 64\n    • Memory: 201.3 GB / 512.0 GB (39.3%)\n  ```\n\n### get_node_status\nGet detailed status of a specific node.\n\n- Parameters:\n  - `node` (string, required): Name of the node\n- Example Response:\n  ```\n  🖥️ Node: pve-compute-01\n    • Status: ONLINE\n    • Uptime: ⏳ 156d 12h\n    • CPU Usage: 42.3%\n    • CPU Cores: 64 (AMD EPYC 7763)\n    • Memory: 186.5 GB / 512.0 GB (36.4%)\n    • Network: ⬆️ 12.8 GB/s ⬇️ 9.2 GB/s\n    • Temperature: 38°C\n  ```\n\n### get_vms\nList all VMs across the cluster.\n\n- Parameters: None\n- Example Response:\n  ```\n  🗃️ Virtual Machines\n\n  🗃️ prod-db-master (ID: 100)\n    • Status: RUNNING\n    • Node: pve-compute-01\n    • CPU Cores: 16\n    • Memory: 92.3 GB / 128.0 GB (72.1%)\n\n  🗃️ prod-web-01 (ID: 102)\n    • Status: RUNNING\n    • Node: pve-compute-01\n    • CPU Cores: 8\n    • Memory: 12.8 GB / 32.0 GB (40.0%)\n  ```\n\n### get_storage\nList available storage.\n\n- Parameters: None\n- Example Response:\n  ```\n  💾 Storage Pools\n\n  💾 ceph-prod\n    • Status: ONLINE\n    • Type: rbd\n    • Usage: 12.8 TB / 20.0 TB (64.0%)\n    • IOPS: ⬆️ 15.2k ⬇️ 12.8k\n\n  💾 local-zfs\n    • Status: ONLINE\n    • Type: zfspool\n    • Usage: 3.2 TB / 8.0 TB (40.0%)\n    • IOPS: ⬆️ 42.8k ⬇️ 35.6k\n  ```\n\n### get_cluster_status\nGet overall cluster status.\n\n- Parameters: None\n- Example Response:\n  ```\n  ⚙️ Proxmox Cluster\n\n    • Name: enterprise-cloud\n    • Status: HEALTHY\n    • Quorum: OK\n    • Nodes: 4 ONLINE\n    • Version: 8.1.3\n    • HA Status: ACTIVE\n    • Resources:\n      - Total CPU Cores: 192\n      - Total Memory: 1536 GB\n      - Total Storage: 70 TB\n    • Workload:\n      - Running VMs: 7\n      - Total VMs: 8\n      - Average CPU Usage: 38.6%\n      - Average Memory Usage: 42.8%\n  ```\n\n### execute_vm_command\nExecute a command in a VM's console using QEMU Guest Agent.\n\n- Parameters:\n  - `node` (string, required): Name of the node where VM is running\n  - `vmid` (string, required): ID of the VM\n  - `command` (string, required): Command to execute\n- Example Response:\n  ```\n  🔧 Console Command Result\n    • Status: SUCCESS\n    • Command: systemctl status nginx\n    • Node: pve-compute-01\n    • VM: prod-web-01 (ID: 102)\n\n  Output:\n  ● nginx.service - A high performance web server and a reverse proxy server\n     Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)\n     Active: active (running) since Tue 2025-02-18 15:23:45 UTC; 2 months 3 days ago\n  ```\n- Requirements:\n  - VM must be running\n  - QEMU Guest Agent must be installed and running in the VM\n  - Command execution permissions must be enabled in the Guest Agent\n- Error Handling:\n  - Returns error if VM is not running\n  - Returns error if VM is not found\n  - Returns error if command execution fails\n  - Includes command output even if command returns non-zero exit code\n\n## 👨‍💻 Development\n\nAfter activating your virtual environment:\n\n- Run tests: `pytest`\n- Format code: `black .`\n- Type checking: `mypy .`\n- Lint: `ruff .`\n\n## 📁 Project Structure\n\n```\nproxmox-mcp/\n├── src/\n│   └── proxmox_mcp/\n│       ├── server.py          # Main MCP server implementation\n│       ├── config/            # Configuration handling\n│       ├── core/              # Core functionality\n│       ├── formatting/        # Output formatting and themes\n│       ├── tools/             # Tool implementations\n│       │   └── console/       # VM console operations\n│       └── utils/             # Utilities (auth, logging)\n├── tests/                     # Test suite\n├── proxmox-config/\n│   └── config.example.json    # Configuration template\n├── pyproject.toml            # Project metadata and dependencies\n└── LICENSE                   # MIT License\n```\n\n## 📄 License\n\nMIT License\n"}