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:

1. Docker builds the proxmox-mcp image from the Dockerfile

2. The container starts with your .env configuration

3. SSH key is mounted read-only inside the container

4. 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 + tty are required because MCP uses stdio for communication

• .env file is loaded automatically (never committed to git)

• SSH key is mounted at /home/mcp/.ssh/ (container runs as non-root mcp user)

• :ro means 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

* Either TOKEN_ID + TOKEN_SECRET OR USER + PASSWORD is required. Token is recommended.

Creating an API Token in Proxmox

1. Open Proxmox web interface (https://your-proxmox:8006)

2. Go to Datacenter → Permissions → API Tokens

3. Click Add

4. Fill in:

   • User: root@pam (or your user)

   • Token ID: mcp (or any name you want)

   • Privilege Separation: ⚠️ Uncheck this to inherit user permissions

5. Click Add

6. 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

Virtual Machines (QEMU)

Containers (LXC)

LXC containers support the same start/stop/shutdown/reboot/destroy operations as VMs.

Snapshots

Storage

Tasks

SSH (Proxmox Host)

Users

Guest Agent (VM)

Troubleshooting

"Connection refused" error

• Check that PROXMOX_HOST is 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_ID format: 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 mcp user (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_write blocks writes to sensitive files (/etc/shadow, /etc/passwd, etc.)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. 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