Proxmox MCP Server

A read-only MCP (Model Context Protocol) server that allows LLM agents to interact with your Proxmox homelab VMs.

Features

• 📋 List all VMs and containers across your Proxmox cluster

• 🔍 Get detailed VM information including hardware specs, network config, and disks

• 📊 Monitor VM status with real-time CPU, memory, and I/O metrics

• 📈 Historical metrics with hourly, daily, weekly, monthly, or yearly data

• 📸 List VM snapshots to see backup points

• 🖥️ Cluster overview with node status and aggregate resources

All operations are read-only - your VMs are safe!

Quick Start

1. Install UV (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Configure Proxmox credentials

cp .env.example .env
# Edit .env with your Proxmox details

3. Create a read-only API token in Proxmox

1. Go to Datacenter → Permissions → API Tokens

2. Click Add

3. Select a user (or create a new one with PVEAuditor role)

4. Set Token ID (e.g., homelab-mcp)

5. Uncheck "Privilege Separation" if using an auditor user

6. Copy the token secret (shown only once!)

Recommended: Create a dedicated auditor user

# SSH to your Proxmox server
pveum user add mcp-reader@pve
pveum acl modify / -user mcp-reader@pve -role PVEAuditor
pveum user token add mcp-reader@pve proxmox-mcp

4. Run the server

cd proxmox-mcp

# SSE mode (recommended for remote access)
uv run proxmox-mcp --transport sse

# Or stdio mode (for local VS Code/CLI usage)
uv run proxmox-mcp --transport stdio

Alternative: Install globally with pip

pip install -e .
proxmox-mcp --transport sse

Available Tools

Configuration

All settings can be configured via environment variables or a .env file:

Using with LLM Clients

VS Code with GitHub Copilot

Add to your VS Code settings.json or user mcp.json:

{
  "servers": {
    "proxmox": {
      "url": "http://your-server:8080/sse"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "proxmox": {
      "url": "http://your-server:8080/sse"
    }
  }
}

Local stdio mode

For local usage, you can run with stdio transport:

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/proxmox-mcp",
        "proxmox-mcp",
        "--transport", "stdio"
      ]
    }
  }
}

Example Queries

Once connected, you can ask your LLM:

• "List all my VMs"

• "What's the status of VM 100?"

• "Show me the CPU usage history for my plex server"

• "Which VMs are currently stopped?"

• "How much memory is my cluster using?"

Security Notes

1. Use API tokens instead of username/password

2. Use the PVEAuditor role for true read-only access

3. Run behind a reverse proxy with HTTPS in production

4. Firewall the MCP port to trusted networks only

Development

cd proxmox-mcp

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/

License

MIT