Proxmox Manager - Proxmox MCP Server
ProxmoxMCP
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
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:
- Install dependencies:
- Create configuration:
- Edit
proxmox-config/config.json:
Verifying Installation
- Check Python environment:
- Run the tests:
- Verify configuration:You should see either:
Configuration
Proxmox API Token Setup
- Log into your Proxmox web interface
- Navigate to Datacenter -> Permissions -> API Tokens
- Create a new API token:
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:
get_node_status
Get detailed status of a specific node.
- Parameters:
- Example Response:
get_vms
List all VMs across the cluster.
- Parameters: None
- Example Response:
get_storage
List available storage.
- Parameters: None
- Example Response:
get_cluster_status
Get overall cluster status.
- Parameters: None
- Example Response:
execute_vm_command
Execute a command in a VM's console using QEMU Guest Agent.
- Parameters:
- Example Response:
- Requirements:
- Error Handling:
Development
After activating your virtual environment:
- Run tests:
pytest
- Format code:
black .
- Type checking:
mypy .
- Lint:
ruff .
Project Structure
License
MIT License
Proxmox Manager - Proxmox MCP Server
ProxmoxMCP
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
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:
- Install dependencies:
- Create configuration:
- Edit
proxmox-config/config.json:
Verifying Installation
- Check Python environment:
- Run the tests:
- Verify configuration:You should see either:
Configuration
Proxmox API Token Setup
- Log into your Proxmox web interface
- Navigate to Datacenter -> Permissions -> API Tokens
- Create a new API token:
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:
get_node_status
Get detailed status of a specific node.
- Parameters:
- Example Response:
get_vms
List all VMs across the cluster.
- Parameters: None
- Example Response:
get_storage
List available storage.
- Parameters: None
- Example Response:
get_cluster_status
Get overall cluster status.
- Parameters: None
- Example Response:
execute_vm_command
Execute a command in a VM's console using QEMU Guest Agent.
- Parameters:
- Example Response:
- Requirements:
- Error Handling:
Development
After activating your virtual environment:
- Run tests:
pytest
- Format code:
black .
- Type checking:
mypy .
- Lint:
ruff .
Project Structure
License
MIT License