A Model Context Protocol (MCP) server that integrates with your Proxmox Virtual Environment to manage virtual machines, containers, and infrastructure with enhanced flexibility through SSH fallbacks.
This MCP server provides a secure and robust interface for AI assistants to audit nodes, manage VM lifecycles, and provision new infrastructure directly from the chat interface. It intelligently switches between the QEMU Guest Agent and SSH for maximum reliability.
All tools are prefixed with proxmox_ to ensure they are uniquely identifiable.
proxmox_list_nodes: Lists all physical nodes in the Proxmox cluster with status.proxmox_list_vms: Lists all QEMU VMs and LXC Containers on a specific node.proxmox_start_vm: Sends a start signal to a VM or Container.proxmox_stop_vm: Sends a shutdown signal to a VM or Container.proxmox_create_vm_from_template: Creates a new VM by cloning an existing template.proxmox_delete_vm: Deletes a stopped VM or Container.proxmox_update_vm: Updates VM specs (cores, memory) and restarts it.proxmox_get_vm_stats: Get real-time statistics for a specific VM.proxmox_migrate_vm: Migrates a VM or Container to another node.proxmox_create_lxc: Creates a new LXC Container from a template.proxmox_create_snapshot: Creates a VM snapshot.proxmox_list_snapshots: Lists snapshots for a VM.proxmox_rollback_snapshot: Rolls back a VM to a specific snapshot.proxmox_delete_snapshot: Deletes a VM snapshot.proxmox_create_backup: Triggers a vzdump backup for a VM/CT.proxmox_list_backups: Lists available backup files.proxmox_restore_backup: Restores a VM from a backup file.proxmox_list_storage: Lists storage usage on a specific node.proxmox_list_content: Lists ISOs and Container Templates on storage.The following tools provide a hybrid approach for interacting with a VM's guest operating system. They will first attempt to use the QEMU Guest Agent. If the agent is not installed or unavailable, they will automatically fall back to using SSH/SFTP, providing a much more robust experience.
proxmox_install_software: Installs software inside a VM.proxmox_execute_command: Executes an arbitrary shell command inside a VM.proxmox_read_file_vm: Reads a file from inside the VM. Uses SFTP for the SSH fallback.proxmox_write_file_vm: Writes a file inside the VM. Uses SFTP for the SSH fallback.To use the fallback mechanism, you must provide the following optional parameters in your tool call, in addition to the standard ones (node, vmid, etc.):
ip_address: The IP address of the virtual machine.ssh_user: The username for the SSH connection.ssh_password or ssh_private_key: The password or the raw private key string for authentication.ssh_port: (Optional) The SSH port, defaults to 22.proxmox_add_firewall_rule: Adds a firewall rule to a VM.proxmox_list_firewall_rules: Lists firewall rules for a VM.To ensure the server remains responsive, the following timeouts are in place:
proxmox_install_software: 5 minutes.proxmox_execute_command: 1 minute.proxmox_install_software: 2 minutes.proxmox_execute_command: 1 minute.Deployment can be done via Docker CLI for local on-demand use or Docker Compose for a persistent remote service.
Ideal for integration with local tools like Docker Desktop's MCP feature.
Build the Image:
docker-compose build
# or
docker build -t proxmox-mcp-server .
Run On-Demand via Docker CLI:
docker run -i --rm \
-e PROXMOX_URL="https://192.168.1.10:8006" \
-e PROXMOX_USER="root@pam" \
-e PROXMOX_PASSWORD="yourpassword" \
-e PROXMOX_VERIFY_SSL="false" \
proxmox-mcp-server
Recommended for deploying as a persistent service on a remote server. The included docker-compose.yaml uses Caddy as a reverse proxy for automatic HTTPS and Token Authentication.
Configure Environment:
Create a .env file on your remote machine:
# Proxmox Credentials
PROXMOX_URL=https://your-proxmox-ip:8006
PROXMOX_USER=root@pam
PROXMOX_PASSWORD=yourpassword
PROXMOX_VERIFY_SSL=false
# MCP Security: Set a strong secret token
MCP_AUTH_TOKEN=my-super-secret-token-123
Also create a proxmox_password.txt file with your password if you prefer using Docker secrets.
Build & Run:
docker-compose up --build -d
https://your-server-ip:8443/.This method provides the best security and resource efficiency by running the container only when needed, tunneled through a standard SSH connection.
Server-Side Setup:
docker build -t proxmox-mcp-server .Client-Side Configuration: For secure remote access via SSH tunnel, configure your MCP client with the following:
{
"mcpServers": {
"remote-proxmox-ssh": {
"command": "ssh",
"args": [
"-i", "/path/to/your/private_ssh_key",
"user@your-remote-server-ip",
"docker", "run", "-i", "--rm",
"-e", "PROXMOX_URL=https://your-proxmox-ip:8006",
"-e", "PROXMOX_USER=root@pam",
"-e", "PROXMOX_PASSWORD=yourpassword",
"proxmox-mcp-server:latest"
]
}
}
}
For direct installation and execution on your local client machine using the repository.
Clone the Repository:
git clone https://github.com/rezytijo/MCP-Collection.git
cd MCP-Collection/Proxmox
Install Dependencies:
pip install -r requirements.txt
Client-Side Configuration: Configure your MCP client to run the Python script directly. Below are examples for popular MCP-compatible tools.
Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"Proxmox Test": {
"command": "python",
"args": [
"path/to/proxmox_server.py"
],
"env": {
"PROXMOX_URL": "https://your-proxmox-ip:8006",
"PROXMOX_USER": "root@pam",
"PROXMOX_PASSWORD": "yourpassword",
"MCP_AUTH_TOKEN": "secret-token",
"PROXMOX_VERIFY_SSL": "false"
}
}
}
}
In your Gemini MCP configuration, add a server entry with the Python command:
{
"mcpServers": {
"proxmox-gemini": {
"command": "python",
"args": ["path/to/proxmox_server.py"],
"env": {
"PROXMOX_URL": "https://your-proxmox-ip:8006",
"PROXMOX_USER": "root@pam",
"PROXMOX_PASSWORD": "yourpassword",
"PROXMOX_VERIFY_SSL": "false"
}
}
}
}
Configure in your Copilot MCP settings:
{
"mcpServers": {
"proxmox-copilot": {
"command": "python",
"args": ["path/to/proxmox_server.py"],
"env": {
"PROXMOX_URL": "https://your-proxmox-ip:8006",
"PROXMOX_USER": "root@pam",
"PROXMOX_PASSWORD": "yourpassword",
"PROXMOX_VERIFY_SSL": "false"
}
}
}
}
In LM Studio's MCP server configuration:
{
"mcpServers": {
"proxmox-lmstudio": {
"command": "python",
"args": ["path/to/proxmox_server.py"],
"env": {
"PROXMOX_URL": "https://your-proxmox-ip:8006",
"PROXMOX_USER": "root@pam",
"PROXMOX_PASSWORD": "yourpassword",
"PROXMOX_VERIFY_SSL": "false"
}
}
}
}
MIT License
Content type
Image
Digest
sha256:d758f4af3…
Size
160.9 MB
Last updated
8 months ago
docker pull rezytijo/proxmox-mcp-server