hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrations
Supports viewing Ceph storage pools in the Proxmox environment, including status, usage, and IOPS metrics.
Allows interaction with Proxmox hypervisors, providing tools for managing nodes, VMs, and containers. Features include listing nodes in the Proxmox cluster, getting detailed node status, listing VMs, accessing storage information, checking cluster status, and executing commands in VM consoles.
Enables execution of commands in a VM's console using QEMU Guest Agent, with full command output reported back to the user.
🚀 Proxmox Manager - Proxmox MCP Server
A Python-based Model Context Protocol (MCP) server for interacting with Proxmox hypervisors, providing a clean interface for managing nodes, VMs, and containers.
🏗️ Built With
- Cline - Autonomous coding agent - Go faster with Cline.
- Proxmoxer - Python wrapper for Proxmox API
- MCP SDK - Model Context Protocol SDK
- Pydantic - Data validation using Python type annotations
✨ Features
- 🤖 Full integration with Cline
- 🛠️ Built with the official MCP SDK
- 🔒 Secure token-based authentication with Proxmox
- 🖥️ Tools for managing nodes and VMs
- 💻 VM console command execution
- 📝 Configurable logging system
- ✅ Type-safe implementation with Pydantic
- 🎨 Rich output formatting with customizable themes
https://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b
📦 Installation
Prerequisites
- UV package manager (recommended)
- Python 3.10 or higher
- Git
- Access to a Proxmox server with API token credentials
Before starting, ensure you have:
- Proxmox server hostname or IP
- Proxmox API token (see API Token Setup)
- UV installed (
pip install uv
)
Option 1: Quick Install (Recommended)
- Clone and set up environment:Copy
- Install dependencies:Copy
- Create configuration:Copy
- Edit
proxmox-config/config.json
:Copy
Verifying Installation
- Check Python environment:Copy
- Run the tests:Copy
- Verify configuration:You should see either:Copy
- A successful connection to your Proxmox server
- Or a connection error (if Proxmox details are incorrect)
⚙️ Configuration
Proxmox API Token Setup
- Log into your Proxmox web interface
- Navigate to Datacenter -> Permissions -> API Tokens
- Create a new API token:
- Select a user (e.g., root@pam)
- Enter a token ID (e.g., "mcp-token")
- Uncheck "Privilege Separation" if you want full access
- Save and copy both the token ID and secret
🚀 Running the Server
Development Mode
For testing and development:
Cline Desktop Integration
For Cline users, add this configuration to your MCP settings file (typically at ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
):
To help generate the correct paths, you can use this command:
Important:
- All paths must be absolute
- The Python interpreter must be from your virtual environment
- The PYTHONPATH must point to the src directory
- Restart VSCode after updating MCP settings
🔧 Available Tools
The server provides the following MCP tools for interacting with Proxmox:
get_nodes
Lists all nodes in the Proxmox cluster.
- Parameters: None
- Example Response:Copy
get_node_status
Get detailed status of a specific node.
- Parameters:
node
(string, required): Name of the node
- Example Response:Copy
get_vms
List all VMs across the cluster.
- Parameters: None
- Example Response:Copy
get_storage
List available storage.
- Parameters: None
- Example Response:Copy
get_cluster_status
Get overall cluster status.
- Parameters: None
- Example Response:Copy
execute_vm_command
Execute a command in a VM's console using QEMU Guest Agent.
- Parameters:
node
(string, required): Name of the node where VM is runningvmid
(string, required): ID of the VMcommand
(string, required): Command to execute
- Example Response:Copy
- Requirements:
- VM must be running
- QEMU Guest Agent must be installed and running in the VM
- Command execution permissions must be enabled in the Guest Agent
- Error Handling:
- Returns error if VM is not running
- Returns error if VM is not found
- Returns error if command execution fails
- Includes command output even if command returns non-zero exit code
👨💻 Development
After activating your virtual environment:
- Run tests:
pytest
- Format code:
black .
- Type checking:
mypy .
- Lint:
ruff .
📁 Project Structure
📄 License
MIT License
This server cannot be installed
A Python-based server enabling interaction with Proxmox hypervisors. It supports secure authentication and provides tools for managing nodes, VMs, clusters, and storage.