Proxmox MCP Server

A Model Context Protocol (MCP) server for the Proxmox Virtual Environment API. It exposes 338 tools covering nodes, VMs, containers, storage, clustering and HA, users and permissions, firewall, disks, Ceph, ACME certificates, SDN, notifications and resource pools.

Built with Python and uv for fast, reliable dependency management.

Features

Agent-to-Agent (A2A) Protocol Support

This server implements the A2A protocol for seamless agent-to-agent communication. The included agent-card.json file provides:

• Structured agent capabilities - Detailed skill definitions for AI-to-AI discovery

• Authentication specifications - Clear auth requirements for automated integration

• Tool catalog - Complete inventory of available operations organized by category

• MCP protocol support - Native Model Context Protocol implementation

Use Cases:

• Multi-agent orchestration systems

• Automated infrastructure workflows

• Agent discovery and composition

• Cross-system AI collaboration

See the A2A Protocol Documentation section below for integration details.

Proxmox VE API Coverage

See Available Tools for how to browse the full list.

Related MCP server: ProxmoxMCP-Plus

Quick Start

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Run setup script
chmod +x setup.sh
./setup.sh

# 3. Set environment variables
export PROXMOX_HOST="192.168.1.100"
export PROXMOX_USER="root@pam"
export PROXMOX_TOKEN_NAME="automation"
export PROXMOX_TOKEN_VALUE="your-token-here"

# 4. Test connection
./test-connection.sh

# 5. Configure Claude Desktop and restart

See QUICKSTART.md for detailed instructions.

Installation

Prerequisites

• Python 3.10 or higher

• uv package manager

• Proxmox VE 6.0 or later

Setup

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

# Clone or download this repository
cd proxmox-mcp-server

# Run setup script (installs dependencies)
./setup.sh

# Or manually:
uv sync

Docker

A multi-arch image is published to GitHub Container Registry on every push to main and for each release tag:

docker pull ghcr.io/thanhan92-f1/proxmox-mcp-server:latest   # or a version tag, e.g. :2.2.0

MCP clients talk to the server over stdio, so run the container interactively (-i) and pass configuration as environment variables:

docker run -i --rm --env-file .env ghcr.io/thanhan92-f1/proxmox-mcp-server:latest

docker-compose.yaml in this repository does the same using your .env file (copy .env.example to get started).

Configuration

The server is configured via environment variables:

Required Variables

• PROXMOX_HOST: Proxmox server hostname or IP address, without scheme or port (e.g. 192.168.1.100, not https://192.168.1.100:8006)

• PROXMOX_USER: Username (e.g., root@pam, admin@pve)

Authentication (choose one method)

Option 1: API Token (Recommended)

• PROXMOX_TOKEN_NAME: API token name

• PROXMOX_TOKEN_VALUE: API token value

Option 2: Password

• PROXMOX_PASSWORD: User password

Optional Variables

• PROXMOX_PORT: API port (default: 8006)

• PROXMOX_VERIFY_SSL: Verify SSL certificates (default: false)

• PROXMOX_READ_ONLY: Block all writes — only GET requests are allowed; any create/update/delete/action tool is refused (default: false). 149 of the 338 tools are read-only and keep working. Three read-style tools also send POST requests and are blocked: vm_agent_ping, plus get_vm_vnc_proxy and get_vm_spice_proxy, which create console access tickets

When running from a clone, a .env file in the project directory is loaded automatically. See .env.example.

Setting Up Proxmox Authentication

Creating an API Token (Recommended)

1. Log into your Proxmox web interface

2. Navigate to Datacenter → Permissions → API Tokens

3. Click Add and create a token for your user

4. Uncheck "Privilege Separation" to inherit user permissions

5. Copy the Token ID and Secret (you won't see it again!)

Example token format:

PROXMOX_TOKEN_NAME=automation
PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The full token identifier will be: root@pam!automation

Using Password Authentication

Simply set your user password:

export PROXMOX_PASSWORD=yourpassword

MCP Configuration

Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

With API Token (Recommended)

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/proxmox-mcp-server",
        "run",
        "proxmox-mcp-server"
      ],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "automation",
        "PROXMOX_TOKEN_VALUE": "your-token-value-here"
      }
    }
  }
}

With Password

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/proxmox-mcp-server",
        "run",
        "proxmox-mcp-server"
      ],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_PASSWORD": "your-password-here"
      }
    }
  }
}

With Docker

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_TOKEN_NAME",
        "-e", "PROXMOX_TOKEN_VALUE",
        "ghcr.io/thanhan92-f1/proxmox-mcp-server:latest"
      ],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "automation",
        "PROXMOX_TOKEN_VALUE": "your-token-value-here"
      }
    }
  }
}

Important: For the uv configurations, use the absolute path to your project directory!

Available Tools

The server registers 338 tools, grouped by API area in proxmox_mcp/tools/, one module per area. Tool names follow the Proxmox API: list_*, get_*, create_*, update_*/set_*, delete_*, plus actions such as start_vm, migrate_container or apply_sdn.

Some commonly used tools:

Your MCP client lists every tool with its full input schema. To print them all locally:

uv run python -c "from proxmox_mcp.server import ALL_TOOLS; print('\n'.join(sorted(t.name for t in ALL_TOOLS)))"

See USAGE.md for worked examples.

Example Usage

Once configured, you can ask Claude to interact with your Proxmox environment:

"Can you list all VMs in my Proxmox cluster?"

"What's the status of VM 100 on node pve1?"

"Start VM 105 on node pve1"

"Create a snapshot called 'backup-2025' for VM 100 on pve1"

"Show me the storage usage on all nodes"

"List all running tasks in the cluster"

"Clone VM 9000 to a new VM called web-02 and start it"

"Run df -h inside VM 120 using the guest agent and show me the output"

Development

# Install dependencies
uv sync

# Run the server directly
uv run proxmox-mcp-server

# Run with custom environment
PROXMOX_HOST=192.168.1.100 \
PROXMOX_USER=root@pam \
PROXMOX_TOKEN_NAME=automation \
PROXMOX_TOKEN_VALUE=your-token \
uv run proxmox-mcp-server

# Lint and format (dev dependencies are installed by `uv sync`)
uv run ruff check .
uv run black .

Project Structure

proxmox-mcp-server/
├── proxmox_mcp/
│   ├── server.py             # MCP server entrypoint and tool registry
│   ├── client.py             # Proxmox API client (token/password auth)
│   └── tools/                # Tool definitions and handlers, one module per API area
│       ├── nodes.py, qemu.py, lxc.py, storage.py, cluster.py, access.py
│       └── firewall.py, disks.py, ceph.py, acme.py, sdn.py, notifications.py, pools.py
├── Dockerfile                # Container image (stdio transport)
├── docker-compose.yaml       # Compose setup using .env
├── agent-card.json           # A2A agent card
├── pyproject.toml            # Project configuration
├── uv.lock                   # Locked dependencies
├── .env.example              # Environment variable template
├── setup.sh                  # Automated setup script
├── test-connection.sh        # Connection test script
├── README.md                 # This file
├── CHANGELOG.md              # Release history
├── QUICKSTART.md             # 5-minute setup guide
├── SETUP.md                  # Detailed setup guide
└── USAGE.md                  # Usage examples

Security Considerations

• API Tokens are more secure than password authentication as they can be revoked independently

• For monitoring-only deployments, set PROXMOX_READ_ONLY=true and use a PVEAuditor token. The flag stops the server from sending writes, and the token permissions enforce the same limit on the Proxmox side

• Set PROXMOX_VERIFY_SSL=true in production environments with valid SSL certificates

• Grant minimal required permissions to API tokens. The server exposes destructive operations (deleting VMs, wiping disks, running commands inside guests via the agent), and the token's permissions are the only thing limiting what a connected AI client can do. For monitoring-only use, a token with the PVEAuditor role is enough

• Store credentials securely and never commit them to version control

• Consider network restrictions (firewall rules) for API access

Troubleshooting

Authentication Errors

• Verify your credentials are correct

• Check that the user has appropriate permissions

• For API tokens, ensure the token hasn't expired or been revoked

• Ensure "Privilege Separation" was unchecked when creating the token

Connection Errors

• Verify PROXMOX_HOST and PROXMOX_PORT are correct

• Check network connectivity to the Proxmox host

• If using SSL verification, ensure certificates are valid

• Test with: curl -k https://YOUR_HOST:8006/api2/json/version

Permission Errors

• The user/token needs appropriate privileges for the operations

• Common required privileges: VM.Monitor, VM.Audit, Datastore.Audit, Sys.Audit, VM.PowerMgmt, VM.Snapshot

Debug Mode

To see detailed logs, check stderr output when running the server. The server logs authentication method and connection status to stderr (visible in Claude Desktop logs).

Tools Not Showing in Claude

• Verify the path in Claude config is absolute, not relative

• Check that the config file is valid JSON

• Ensure you completely quit and restarted Claude Desktop (not just closed the window)

• Check Claude Desktop logs for errors

Testing Connection

Before configuring Claude, test your Proxmox connection:

# Set environment variables
export PROXMOX_HOST="192.168.1.100"
export PROXMOX_USER="root@pam"
export PROXMOX_TOKEN_NAME="automation"
export PROXMOX_TOKEN_VALUE="your-token-here"

# Run test script
./test-connection.sh

The script will verify:

1. Connection to Proxmox

2. API availability

3. Authentication

4. Permission to list nodes

5. Access to cluster resources

A2A Protocol

Overview

This Proxmox MCP server implements the Agent-to-Agent (A2A) protocol, enabling AI agents to discover, communicate with, and orchestrate infrastructure management tasks autonomously.

Agent Card

The agent-card.json file serves as the agent's identity and capability manifest. It provides:

Location: /agent-card.json (repository root)

Contents:

• Agent name, version, and description

• MCP protocol version and capabilities

• Authentication methods and requirements

• Skill catalog organized by functional category

• Required permissions and dependencies

• Endpoint configuration

Available Skills

The agent card lists all 338 tools in 13 skill categories, generated from the server's tool registry. Each entry has the tool's name, description and inputs:

Agent-to-Agent Integration

Discovery

Other agents can discover this agent's capabilities by reading the agent card:

import json

# Load agent card
with open('agent-card.json') as f:
    agent_card = json.load(f)

# Discover capabilities
print(f"Agent: {agent_card['name']}")
print(f"Version: {agent_card['version']}")
print(f"Skills: {len(agent_card['skills'])} categories")

# List available skills
for skill in agent_card['skills']:
    print(f"\n{skill['category']}:")
    for capability in skill['capabilities']:
        print(f"  - {capability['name']}: {capability['description']}")

Authentication Setup

Agents can programmatically configure authentication:

# API Token (recommended)
env_config = {
    "PROXMOX_HOST": "192.168.1.100",
    "PROXMOX_USER": "root@pam",
    "PROXMOX_TOKEN_NAME": "automation",
    "PROXMOX_TOKEN_VALUE": "your-token-value"
}

# Or Password-based
env_config = {
    "PROXMOX_HOST": "192.168.1.100",
    "PROXMOX_USER": "root@pam",
    "PROXMOX_PASSWORD": "your-password"
}

Tool Invocation

Agents communicate via MCP protocol:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to the agent
server_params = StdioServerParameters(
    command="uv",
    args=["--directory", "/path/to/proxmox-mcp-server", "run", "proxmox-mcp-server"],
    env=env_config
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize session
        await session.initialize()

        # List available tools
        tools = await session.list_tools()

        # Call a tool
        result = await session.call_tool("list_vms", arguments={})
        print(result.content)

Multi-Agent Orchestration Example

Example workflow with multiple agents:

# Agent orchestration: VM backup workflow
async def backup_workflow():
    # 1. Proxmox agent: List VMs
    vms = await proxmox_agent.call_tool("list_vms", {})

    # 2. Proxmox agent: Create snapshots for each VM
    for vm in vms['data']:
        snapshot_name = f"backup-{datetime.now().strftime('%Y%m%d-%H%M%S')}"
        await proxmox_agent.call_tool("create_vm_snapshot", {
            "node": vm['node'],
            "vmid": vm['vmid'],
            "snapname": snapshot_name
        })

    # 3. Storage agent: Verify backup storage capacity
    storage_status = await storage_agent.call_tool("check_capacity", {})

    # 4. Notification agent: Send completion report
    await notification_agent.call_tool("send_alert", {
        "message": f"Backup completed: {len(vms['data'])} VMs"
    })

A2A Protocol Benefits

For AI Agents:

• Self-documenting - Agent card provides complete capability discovery

• Type-safe - Structured skill definitions with input/output schemas

• Composable - Skills can be combined for complex workflows

• Secure - Clear authentication requirements and permissions

For Orchestration Systems:

• Dynamic discovery - Find and integrate agents at runtime

• Capability matching - Match tasks to agent skills automatically

• Parallel execution - Coordinate multiple agents simultaneously

• Error handling - Standardized error responses and retry logic

Integration Examples

Example 1: Infrastructure Monitoring Agent

# Monitoring agent that uses Proxmox agent skills
async def monitor_infrastructure():
    # Get cluster status
    cluster = await proxmox_agent.call_tool("get_cluster_status", {})

    # Get all nodes
    nodes = await proxmox_agent.call_tool("list_nodes", {})

    # Check each node's status
    for node in nodes['data']:
        status = await proxmox_agent.call_tool("get_node_status", {
            "node": node['node']
        })

        # Alert if resource usage is high
        if status['data']['cpu'] > 0.9:
            await alert_agent.send_alert(f"High CPU on {node['node']}")

API Documentation

For more information about the Proxmox VE API:

• Proxmox VE API Documentation

• API Viewer

• Proxmox VE Administration Guide

Dependencies

• mcp (>=1.0.0, <2): Model Context Protocol SDK. 2.x changed the server API and is not supported yet

• httpx (>=0.28.1): Async HTTP client for the Proxmox API

• python-dotenv (>=1.2.3): Loads configuration from .env

Roadmap

• Streamable-HTTP transport for running the server as a network service (#24, #29)

• Support for mcp 2.x

• Automatic ticket refresh for long-running password-authenticated sessions

• Automated test suite

See CHANGELOG.md for what has shipped.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Areas for improvement:

• Additional tools/features

• Better error handling

• Performance optimizations

• Documentation improvements

• Test coverage

• Bug fixes

License

MIT. See LICENSE.

Related Projects

• Model Context Protocol

• Proxmox VE

• uv - Python Package Manager

• MCP Servers Collection

Support

If you encounter issues:

1. Check the documentation files:

   • QUICKSTART.md - Quick setup

   • SETUP.md - Detailed setup with security

   • USAGE.md - Usage examples

2. Test your connection with ./test-connection.sh

3. Check Claude Desktop logs for errors

4. Verify Proxmox server logs: /var/log/pve/

5. Review Proxmox API documentation

Acknowledgments

This project uses:

• The Model Context Protocol by Anthropic

• Proxmox VE API

• Python httpx for HTTP requests

• uv for fast Python package management

Ready to get started? → See QUICKSTART.md

Need detailed setup? → See SETUP.md

Want examples? → Check USAGE.md