Proxmox MCP server for AI agents

ProxmoxMCP-Plus is an enhanced Python-based Model Context Protocol (MCP) server that provides comprehensive management capabilities for Proxmox virtualization platforms. It offers complete VM lifecycle management, container support, and OpenAPI integration, making it ideal for automating Proxmox operations through natural language interfaces.

Prerequisites

Before installing, ensure you have:

Python 3.9 or higher
UV package manager (recommended)
Git
Access to a Proxmox server with API token credentials

Installation

Quick Install (Recommended)

Clone and set up environment:

# Clone repository
git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git
cd ProxmoxMCP-Plus

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

Install dependencies:

# Install with development dependencies
uv pip install -e ".[dev]"

Create configuration:

# Create config directory and copy template
mkdir -p proxmox-config
cp proxmox-config/config.example.json proxmox-config/config.json

Edit proxmox-config/config.json:

{
    "proxmox": {
        "host": "PROXMOX_HOST",        # Required: Your Proxmox server address
        "port": 8006,                  # Optional: Default is 8006
        "verify_ssl": false,           # Optional: Set false for self-signed certs
        "service": "PVE"               # Optional: Default is PVE
    },
    "auth": {
        "user": "USER@pve",            # Required: Your Proxmox username
        "token_name": "TOKEN_NAME",    # Required: API token ID
        "token_value": "TOKEN_VALUE"   # Required: API token value
    },
    "logging": {
        "level": "INFO",               # Optional: DEBUG for more detail
        "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
        "file": "proxmox_mcp.log"      # Optional: Log to file
    }
}

Verifying Installation

Check Python environment:

python -c "import proxmox_mcp; print('Installation OK')"

Run the tests:
```
pytest
```

Verify configuration:

# Linux/macOS
PROXMOX_MCP_CONFIG="proxmox-config/config.json" python -m proxmox_mcp.server

# Windows (PowerShell)
$env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"; python -m proxmox_mcp.server

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:

# Activate virtual environment first
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# Run the server
python -m proxmox_mcp.server

OpenAPI Deployment (Production Ready)

Deploy as standard OpenAPI REST endpoints for integration with Open WebUI and other applications.

Quick OpenAPI Start

# Install mcpo (MCP-to-OpenAPI proxy)
pip install mcpo

# Start OpenAPI service on port 8811
./start_openapi.sh

Docker Deployment

# Build and run with Docker
docker build -t proxmox-mcp-api .
docker run -d --name proxmox-mcp-api -p 8811:8811 \
  -v $(pwd)/proxmox-config:/app/proxmox-config proxmox-mcp-api

# Or use Docker Compose
docker-compose up -d

Access OpenAPI Service

Once deployed, access your service at:

API Documentation: http://your-server:8811/docs
OpenAPI Specification: http://your-server:8811/openapi.json
Health Check: http://your-server:8811/health

Available Tools & API Endpoints

VM Management

Create VM

Create a new virtual machine with specified resources.

API Endpoint:

POST /create_vm
Content-Type: application/json

{
    "node": "pve",
    "vmid": "200",
    "name": "my-vm",
    "cpus": 1,
    "memory": 2048,
    "disk_size": 10
}

VM Power Management

Start VM: POST /start_vm with {"node": "pve", "vmid": "200"}
Stop VM: POST /stop_vm with {"node": "pve", "vmid": "200"}
Shutdown VM: POST /shutdown_vm with {"node": "pve", "vmid": "200"}
Reset VM: POST /reset_vm with {"node": "pve", "vmid": "200"}
Delete VM: POST /delete_vm with {"node": "pve", "vmid": "200", "force": false}

Container Management

List all LXC containers across the cluster:

POST /get_containers

Monitoring Tools

Get Nodes: POST /get_nodes - Lists all nodes in the Proxmox cluster
Get Node Status: POST /get_node_status - Get detailed status of a specific node
Get VMs: POST /get_vms - List all VMs across the cluster
Get Storage: POST /get_storage - List available storage pools
Get Cluster Status: POST /get_cluster_status - Get overall cluster status and health

Execute VM Command

Execute a command in a VM's console using QEMU Guest Agent.

POST /execute_vm_command
Content-Type: application/json

{
    "node": "pve",
    "vmid": "200",
    "command": "ls -la"
}

Open WebUI Integration

Configure Open WebUI

Access your Open WebUI instance
Navigate to Settings → Connections → OpenAPI
Add new API configuration:

{
  "name": "Proxmox MCP API Plus",
  "base_url": "http://your-server:8811",
  "api_key": "",
  "description": "Enhanced Proxmox Virtualization Management API"
}

Troubleshooting

Common Issues

Port already in use

netstat -tlnp | grep 8811
# Change port if needed
mcpo --port 8812 -- ./start_server.sh

Configuration errors

# Verify config file
cat proxmox-config/config.json

Connection issues

# Test Proxmox connectivity
curl -k https://your-proxmox:8006/api2/json/version

View Logs

# View service logs
tail -f proxmox_mcp.log

# Docker logs
docker logs proxmox-mcp-api -f

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "ProxmoxMCP-Plus" '{"command":"/absolute/path/to/ProxmoxMCP-Plus/.venv/bin/python","args":["-m","proxmox_mcp.server"],"cwd":"/absolute/path/to/ProxmoxMCP-Plus","env":{"PYTHONPATH":"/absolute/path/to/ProxmoxMCP-Plus/src","PROXMOX_MCP_CONFIG":"/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json","PROXMOX_HOST":"your-proxmox-host","PROXMOX_USER":"username@pve","PROXMOX_TOKEN_NAME":"token-name","PROXMOX_TOKEN_VALUE":"token-value","PROXMOX_PORT":"8006","PROXMOX_VERIFY_SSL":"false","PROXMOX_SERVICE":"PVE","LOG_LEVEL":"DEBUG"},"disabled":false,"autoApprove":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "ProxmoxMCP-Plus": {
            "command": "/absolute/path/to/ProxmoxMCP-Plus/.venv/bin/python",
            "args": [
                "-m",
                "proxmox_mcp.server"
            ],
            "cwd": "/absolute/path/to/ProxmoxMCP-Plus",
            "env": {
                "PYTHONPATH": "/absolute/path/to/ProxmoxMCP-Plus/src",
                "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json",
                "PROXMOX_HOST": "your-proxmox-host",
                "PROXMOX_USER": "username@pve",
                "PROXMOX_TOKEN_NAME": "token-name",
                "PROXMOX_TOKEN_VALUE": "token-value",
                "PROXMOX_PORT": "8006",
                "PROXMOX_VERIFY_SSL": "false",
                "PROXMOX_SERVICE": "PVE",
                "LOG_LEVEL": "DEBUG"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "ProxmoxMCP-Plus": {
            "command": "/absolute/path/to/ProxmoxMCP-Plus/.venv/bin/python",
            "args": [
                "-m",
                "proxmox_mcp.server"
            ],
            "cwd": "/absolute/path/to/ProxmoxMCP-Plus",
            "env": {
                "PYTHONPATH": "/absolute/path/to/ProxmoxMCP-Plus/src",
                "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json",
                "PROXMOX_HOST": "your-proxmox-host",
                "PROXMOX_USER": "username@pve",
                "PROXMOX_TOKEN_NAME": "token-name",
                "PROXMOX_TOKEN_VALUE": "token-value",
                "PROXMOX_PORT": "8006",
                "PROXMOX_VERIFY_SSL": "false",
                "PROXMOX_SERVICE": "PVE",
                "LOG_LEVEL": "DEBUG"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

3. Restart Claude Desktop for the changes to take effect