Proxmox MCP Server
BenjaminDuthe/proxmox-mcp
Gerencie infraestrutura Proxmox VE diretamente do Claude
Ver no GitHubServidor MCP que integra Claude com Proxmox VE, permitindo gerenciar VMs, containers LXC, snapshots e armazenamento via linguagem natural. Oferece controle completo sobre infraestrutura virtualizada com suporte a monitoramento de tarefas, gerenciamento de usuários e execução de comandos via SSH ou QEMU Guest Agent.
Instalação
npx convez-ai BenjaminDuthe/proxmox-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de provisionamento e destruição de VMs/containers
- Backup e restauração de snapshots via conversação
- Monitoramento de recursos e tarefas em tempo real
- Execução remota de comandos em hosts Proxmox
Veredito

Solução técnica sólida para equipes que usam Proxmox e querem automatizar operações via Claude. Bem documentada, com suporte Docker e autenticação por token — pronta para ambientes de produção com expertise em infraestrutura.
README
A tradução para o português deste README ainda está na fila.
Proxmox MCP Server
A Model Context Protocol (MCP) server that enables Claude to manage Proxmox VE infrastructure — VMs, LXC containers, snapshots, storage, and more.
Features
- Node Management — List cluster nodes, monitor CPU/RAM/disk metrics
- VM & Container Control — Start, stop, reboot, destroy QEMU VMs and LXC containers
- Snapshots — Create, list, delete, and rollback snapshots
- Storage — Browse storage pools and content (ISOs, backups, templates)
- Task Monitoring — Track Proxmox tasks in real-time
- SSH Access — Execute commands directly on Proxmox host
- User Management — Create, update, delete Proxmox users
- Guest Agent — Execute commands inside VMs via QEMU Guest Agent
- Docker Ready — Run as a container with minimal configuration
Quick Start with Docker Compose
Step 1: Clone the repository
git clone https://github.com/BenjaminDuthe/proxmox-mcp.git
cd proxmox-mcp
Step 2: Create your configuration file
cp .env.example .env
Step 3: Edit .env with your Proxmox credentials
Open .env in your editor and replace the placeholder values:
# ⚠️ REQUIRED - Replace these values with your own
PROXMOX_HOST=<YOUR_PROXMOX_IP> # Example: 192.168.1.10
PROXMOX_PORT=8006 # Default Proxmox port (usually no change needed)
PROXMOX_TOKEN_ID=<YOUR_TOKEN_ID> # Example: root@pam!mcp
PROXMOX_TOKEN_SECRET=<YOUR_TOKEN_SECRET> # Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
PROXMOX_VERIFY_SSL=false # Set to 'true' if you have valid SSL certificates
PROXMOX_TIMEOUT=30
# 📌 OPTIONAL - For SSH access to Proxmox host
PROXMOX_SSH_USER=root
PROXMOX_SSH_KEY_PATH=<PATH_TO_YOUR_SSH_KEY> # Example: ~/.ssh/id_rsa
📋 Legend:
<YOUR_PROXMOX_IP>→ Your Proxmox server IP address (e.g.,192.168.1.10)<YOUR_TOKEN_ID>→ API token ID created in Proxmox (e.g.,root@pam!mytoken)<YOUR_TOKEN_SECRET>→ The secret shown when creating the token (UUID format)<PATH_TO_YOUR_SSH_KEY>→ Path to your SSH private key (optional, for SSH tools)
Step 4: Generate SSH key (optional, for SSH tools)
If you want to use SSH tools (ssh_execute, ssh_read_file, etc.):
# Generate a dedicated SSH key
ssh-keygen -t ed25519 -f ~/.ssh/id_proxmox_mcp -N "" -C "proxmox-mcp"
# Copy the public key to your Proxmox server
ssh-copy-id -i ~/.ssh/id_proxmox_mcp.pub root@<YOUR_PROXMOX_IP>
Then update .env:
PROXMOX_SSH_KEY_PATH=~/.ssh/id_proxmox_mcp
Step 5: Start with Docker Compose
docker compose up -d
What happens:
- Docker builds the
proxmox-mcpimage from the Dockerfile - The container starts with your
.envconfiguration - SSH key is mounted read-only inside the container
- MCP server is ready to receive commands
Step 6: Check it's running
# View logs
docker compose logs
# Expected output:
# proxmox-mcp | INFO - Configuration loaded: 192.168.1.10:8006
# proxmox-mcp | INFO - Proxmox client connected
# proxmox-mcp | INFO - MCP server ready
Step 7: Stop/Restart
# Stop
docker compose down
# Restart (after .env changes)
docker compose up -d --force-recreate
# Rebuild (after code changes)
docker compose up -d --build
Docker Compose File Explained
The docker-compose.yml file:
services:
proxmox-mcp:
build: . # Build image from local Dockerfile
image: proxmox-mcp:latest # Image name
container_name: proxmox-mcp # Container name
stdin_open: true # Keep STDIN open (required for MCP protocol)
tty: true # Allocate pseudo-TTY
env_file:
- .env # Load environment variables from .env file
environment:
# Override SSH key path for container filesystem
- PROXMOX_SSH_KEY_PATH=/home/mcp/.ssh/id_proxmox_mcp
volumes:
# Mount your SSH key inside the container (read-only)
- ~/.ssh/id_proxmox_mcp:/home/mcp/.ssh/id_proxmox_mcp:ro
restart: unless-stopped # Auto-restart on failure
Key points:
stdin_open+ttyare required because MCP uses stdio for communication.envfile is loaded automatically (never committed to git)- SSH key is mounted at
/home/mcp/.ssh/(container runs as non-rootmcpuser) :romeans read-only (security best practice)
Alternative: Run with Docker (without Compose)
# Build the image
docker build -t proxmox-mcp .
# Run with .env file
docker run --rm -it --env-file .env proxmox-mcp
# Run with SSH key mounted
docker run --rm -it \
--env-file .env \
-e PROXMOX_SSH_KEY_PATH=/home/mcp/.ssh/id_proxmox_mcp \
-v ~/.ssh/id_proxmox_mcp:/home/mcp/.ssh/id_proxmox_mcp:ro \
proxmox-mcp
Alternative: Local Installation (without Docker)
# Install Python package
pip install -e ".[dev]"
# Run MCP server
python -m proxmox_mcp.server
Configuration Reference
Environment Variables
| Variable | Description | Required | Default |
|---|---|---|---|
PROXMOX_HOST | Proxmox server IP or hostname | Yes | — |
PROXMOX_PORT | API port | No | 8006 |
PROXMOX_TOKEN_ID | API token ID (user@realm!token) | Yes* | — |
PROXMOX_TOKEN_SECRET | API token secret (UUID) | Yes* | — |
PROXMOX_USER | Username (alternative to token) | Yes* | — |
PROXMOX_PASSWORD | Password (alternative to token) | Yes* | — |
PROXMOX_VERIFY_SSL | Verify SSL certificate | No | false |
PROXMOX_TIMEOUT | Request timeout (seconds) | No | 30 |
PROXMOX_SSH_KEY_PATH | Path to SSH private key | No | — |
PROXMOX_SSH_USER | SSH username | No | root |
* Either
TOKEN_ID+TOKEN_SECRETORUSER+PASSWORDis required. Token is recommended.
Creating an API Token in Proxmox
- Open Proxmox web interface (https://your-proxmox:8006)
- Go to Datacenter → Permissions → API Tokens
- Click Add
- Fill in:
- User:
root@pam(or your user) - Token ID:
mcp(or any name you want) - Privilege Separation: ⚠️ Uncheck this to inherit user permissions
- User:
- Click Add
- Copy the token secret immediately (shown only once!)
Your token ID will be: root@pam!mcp
Claude Desktop Configuration
Option 1: With Docker (recommended)
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"proxmox": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env-file", "<PATH_TO_PROJECT>/.env",
"-e", "PROXMOX_SSH_KEY_PATH=/home/mcp/.ssh/id_proxmox_mcp",
"-v", "<PATH_TO_SSH_KEY>:/home/mcp/.ssh/id_proxmox_mcp:ro",
"proxmox-mcp"
]
}
}
}
Replace:
<PATH_TO_PROJECT>→ Full path to the cloned repository (e.g.,/home/user/proxmox-mcp)<PATH_TO_SSH_KEY>→ Full path to your SSH private key (e.g.,/home/user/.ssh/id_proxmox_mcp)
Option 2: With Python (local install)
{
"mcpServers": {
"proxmox": {
"command": "python",
"args": ["-m", "proxmox_mcp.server"],
"cwd": "<PATH_TO_PROJECT>",
"env": {
"PROXMOX_HOST": "<YOUR_PROXMOX_IP>",
"PROXMOX_TOKEN_ID": "<YOUR_TOKEN_ID>",
"PROXMOX_TOKEN_SECRET": "<YOUR_TOKEN_SECRET>",
"PROXMOX_VERIFY_SSL": "false"
}
}
}
}
Replace:
<PATH_TO_PROJECT>→ Full path to the cloned repository<YOUR_PROXMOX_IP>→ Your Proxmox server IP<YOUR_TOKEN_ID>→ Your API token ID (e.g.,root@pam!mcp)<YOUR_TOKEN_SECRET>→ Your API token secret
Available Tools
Nodes
| Tool | Description |
|---|---|
list_nodes | List all cluster nodes with CPU/RAM/disk metrics |
get_node_status | Get detailed status of a specific node |
Virtual Machines (QEMU)
| Tool | Description |
|---|---|
list_vms | List all VMs with status and resource usage |
get_vm_details | Get full VM configuration |
start_vm | Start a VM |
stop_vm | Force stop a VM |
shutdown_vm | Graceful shutdown (ACPI) |
reboot_vm | Reboot a VM |
destroy_vm | Permanently delete a VM and its disks |
Containers (LXC)
| Tool | Description |
|---|---|
list_containers | List all LXC containers |
get_container_details | Get full container configuration |
LXC containers support the same start/stop/shutdown/reboot/destroy operations as VMs.
Snapshots
| Tool | Description |
|---|---|
list_snapshots | List snapshots of a VM/container |
create_snapshot | Create a new snapshot |
delete_snapshot | Delete a snapshot |
rollback_snapshot | Restore VM/container to a snapshot |
Storage
| Tool | Description |
|---|---|
list_storage | List storage pools with usage stats |
get_storage_content | List content (ISOs, backups, images) |
Tasks
| Tool | Description |
|---|---|
list_tasks | List recent Proxmox tasks |
get_task_status | Get detailed task status by UPID |
SSH (Proxmox Host)
| Tool | Description |
|---|---|
ssh_execute | Execute command on Proxmox host |
ssh_read_file | Read file from Proxmox host |
ssh_write_file | Write file to Proxmox host |
fix_apt_repos | Fix APT repos for non-subscription |
Users
| Tool | Description |
|---|---|
list_users | List all Proxmox users |
get_user | Get user details and tokens |
create_user | Create a new user |
update_user | Update user properties |
delete_user | Delete a user |
Guest Agent (VM)
| Tool | Description |
|---|---|
vm_exec | Execute command inside VM |
vm_exec_status | Get async command result |
vm_exec_sync | Execute command and wait for result |
vm_file_read | Read file from inside VM |
vm_file_write | Write file inside VM (protected paths) |
Troubleshooting
"Connection refused" error
- Check that
PROXMOX_HOSTis correct - Verify Proxmox API is accessible:
curl -k https://<YOUR_PROXMOX_IP>:8006/api2/json - Check firewall rules on Proxmox
"Authentication failed" error
- Verify
PROXMOX_TOKEN_IDformat:user@realm!tokenname(e.g.,root@pam!mcp) - Check token secret is correct (no extra spaces)
- Ensure "Privilege Separation" is unchecked on the token
SSH tools not working
- Check SSH key path is correct in
.env - Verify key is authorized on Proxmox:
ssh -i ~/.ssh/id_proxmox_mcp root@<YOUR_PROXMOX_IP> - In Docker, ensure the volume mount path matches
PROXMOX_SSH_KEY_PATH
Docker: "permission denied" on SSH key
- Ensure the SSH key file has correct permissions:
chmod 600 ~/.ssh/id_proxmox_mcp - The container runs as
mcpuser (UID 1000)
Architecture
src/proxmox_mcp/
├── server.py # MCP server entry point
├── client.py # Async Proxmox API client (httpx)
├── ssh_client.py # Async SSH client (asyncssh)
├── config.py # Environment-based configuration
├── models.py # Pydantic models
├── exceptions.py # Custom exceptions
└── tools/ # Tool implementations
├── nodes.py
├── vms.py
├── containers.py
├── snapshots.py
├── storage.py
├── tasks.py
├── ssh.py
└── users.py
Development
Install dev dependencies
pip install -e ".[dev]"
Run tests
pytest -v --cov=proxmox_mcp
Lint and format
ruff check src/
ruff format src/
Security Notes
- Never commit
.env— It contains sensitive credentials - Use API tokens — Prefer tokens over user/password
- Limit token permissions — Create dedicated tokens with minimal required permissions
- Protected paths —
vm_file_writeblocks writes to sensitive files (/etc/shadow,/etc/passwd, etc.)
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This project is licensed under the MIT License — see the LICENSE file for details.
Acknowledgments
- Proxmox VE — Powerful open-source virtualization platform
- Model Context Protocol — Anthropic's protocol for AI tool integration
- Claude — AI assistant by Anthropic