npm version Docker image License: MIT Node.js Version

MCP PVE

MCP server for Proxmox VE. Manage virtual machines, containers, storage, networking, and clusters through natural language in Cursor, Claude Code, and Claude Desktop.

Features

• 117 tools across 12 categories covering the Proxmox VE REST API
• Three access tiers (read-only, read-execute, full) for granular control
• Category filtering via PVE_CATEGORIES to expose only the tools you need
• Zero HTTP dependencies -- uses native fetch (Node 18+)
• Self-signed cert support via PVE_VERIFY_SSL=false
• Docker images for linux/amd64 and linux/arm64 on GHCR
• Remote MCP via HTTP transport (MCP_TRANSPORT=http) using the Streamable HTTP protocol
• TypeScript/ESM with full type safety

API Compatibility

Tested with Proxmox VE 9.2.4.

Quick Start

Run the server directly with npx:

PVE_BASE_URL="https://pve.example.com:8006" \
PVE_TOKEN_ID="root@pam!mcp" \
PVE_TOKEN_SECRET="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
npx -y @samik081/mcp-pve

The server validates your PVE connection on startup and fails immediately with a clear error if credentials are missing or invalid.

Docker

Run with Docker (stdio transport, same as npx):

docker run --rm -i \
  -e PVE_BASE_URL=https://pve.example.com:8006 \
  -e PVE_TOKEN_ID=root@pam!mcp \
  -e PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e PVE_VERIFY_SSL=false \
  ghcr.io/samik081/mcp-pve

To run as a remote MCP server with HTTP transport:

docker run -d -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e PVE_BASE_URL=https://pve.example.com:8006 \
  -e PVE_TOKEN_ID=root@pam!mcp \
  -e PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e PVE_VERIFY_SSL=false \
  ghcr.io/samik081/mcp-pve

The MCP endpoint is available at http://localhost:3000 and a health check at http://localhost:3000/health.

Configuration

Claude Code CLI (recommended):

# Using npx
claude mcp add --transport stdio pve \
  --env PVE_BASE_URL=https://pve.example.com:8006 \
  --env PVE_TOKEN_ID=root@pam!mcp \
  --env PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --env PVE_VERIFY_SSL=false \
  -- npx -y @samik081/mcp-pve

# Using Docker
claude mcp add --transport stdio pve \
  --env PVE_BASE_URL=https://pve.example.com:8006 \
  --env PVE_TOKEN_ID=root@pam!mcp \
  --env PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --env PVE_VERIFY_SSL=false \
  -- docker run --rm -i ghcr.io/samik081/mcp-pve

# Using remote HTTP (connect to a running Docker container or HTTP server)
claude mcp add --transport http pve http://localhost:3000

JSON config (works with Claude Code .mcp.json, Claude Desktop claude_desktop_config.json, Cursor .cursor/mcp.json):

{
  "mcpServers": {
    "pve": {
      "command": "npx",
      "args": ["-y", "@samik081/mcp-pve"],
      "env": {
        "PVE_BASE_URL": "https://pve.example.com:8006",
        "PVE_TOKEN_ID": "root@pam!mcp",
        "PVE_TOKEN_SECRET": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "PVE_VERIFY_SSL": "false"
      }
    }
  }
}

Docker (stdio):

{
  "mcpServers": {
    "pve": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "PVE_BASE_URL=https://pve.example.com:8006",
        "-e", "PVE_TOKEN_ID=root@pam!mcp",
        "-e", "PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "-e", "PVE_VERIFY_SSL=false",
        "ghcr.io/samik081/mcp-pve"
      ]
    }
  }
}

Remote MCP (connect to a running Docker container or HTTP server):

{
  "mcpServers": {
    "pve": {
      "type": "streamable-http",
      "url": "http://localhost:3000"
    }
  }
}

Access Tiers

Control which tools are available using the PVE_ACCESS_TIER environment variable:

Tier	Tools	Description
full (default)	117	Read, execute, and write -- full control
read-execute	75	Read and execute -- no resource creation/deletion
read-only	53	Read only -- safe for exploration, no state changes

Tier details:

• full: All 117 tools. Includes creating/deleting VMs, containers, storage, users, firewall rules, and more.
• read-execute: 75 tools. All read tools plus power actions (start, stop, migrate), bulk guest actions, OCI image pull, backup execution, and task management.
• read-only: 53 tools. List, get, status, and log tools only. No state changes.

Tools that are not available in your tier are not registered with the MCP server. They will not appear in your AI tool's tool list, keeping the context clean.

Environment Variables

Variable	Required	Default	Description
PVE_BASE_URL	Yes	--	URL of your PVE instance (e.g. https://pve:8006)
PVE_TOKEN_ID	Yes	--	API token ID (user@realm!tokenname)
PVE_TOKEN_SECRET	Yes	--	API token UUID secret
PVE_ACCESS_TIER	No	full	read-only, read-execute, or full
PVE_CATEGORIES	No	(all)	Comma-separated category allowlist
PVE_TOOL_BLACKLIST	No	(none)	Comma-separated list of tool names to exclude (e.g., pve_delete_qemu_vm)
PVE_TOOL_WHITELIST	No	(none)	Comma-separated list of tool names to force-include, bypassing access tier and category filters
PVE_VERIFY_SSL	No	true	Set false for self-signed certs
DEBUG	No	false	Enable debug logging to stderr
MCP_TRANSPORT	No	stdio	Transport mode: stdio (default) or http
MCP_PORT	No	3000	HTTP server port (only used when MCP_TRANSPORT=http)
MCP_HOST	No	0.0.0.0	HTTP server bind address (only used when MCP_TRANSPORT=http)
MCP_EXCLUDE_TOOL_TITLES	No	false	Set true to omit tool titles from registration (saves tokens)

Create API tokens in the PVE UI under Datacenter > Permissions > API Tokens. Make sure to uncheck "Privilege Separation" if you want the token to inherit the user's full permissions.

Available Categories

nodes, qemu, lxc, storage, cluster, access, pools, network, firewall, backup, tasks, ha

Tools

mcp-pve provides 117 tools organized by category. Each tool's Access column shows the minimum tier required: read-only (available in all tiers), read-execute (requires read-execute or full), or full (requires full tier only). The Hints column shows tool behavior: read-only (no state changes), destructive (modifies existing state), idempotent (same result if called twice).

Nodes (8 tools)

Tool	Description	Access	Hints
pve_list_nodes	List all nodes in the cluster	read-only	read-only, idempotent
pve_get_node_status	Get detailed node status (CPU, memory, uptime, load)	read-only	read-only, idempotent
pve_get_node_version	Get PVE version info for a node	read-only	read-only, idempotent
pve_get_node_dns	Get DNS settings for a node	read-only	read-only, idempotent
pve_get_node_time	Get time and timezone info for a node	read-only	read-only, idempotent
pve_get_node_syslog	Get system log entries from a node	read-only	read-only, idempotent
pve_list_node_services	List all system services on a node	read-only	read-only, idempotent
pve_manage_node_service	Start, stop, restart, or reload a node service	read-execute	destructive

QEMU Virtual Machines (20 tools)

Tool	Description	Access	Hints
pve_list_qemu_vms	List all QEMU VMs on a node	read-only	read-only, idempotent
pve_get_qemu_status	Get current VM status (CPU, memory, disk, network)	read-only	read-only, idempotent
pve_get_qemu_config	Get VM configuration	read-only	read-only, idempotent
pve_get_qemu_rrddata	Get RRD statistics over a time period	read-only	read-only, idempotent
pve_list_qemu_snapshots	List all VM snapshots	read-only	read-only, idempotent
pve_start_qemu_vm	Start a VM	read-execute	destructive
pve_stop_qemu_vm	Stop a VM (immediate)	read-execute	destructive
pve_shutdown_qemu_vm	Gracefully shut down a VM	read-execute	destructive
pve_reboot_qemu_vm	Reboot a VM	read-execute	destructive
pve_suspend_qemu_vm	Suspend a VM	read-execute	destructive
pve_resume_qemu_vm	Resume a suspended VM	read-execute	destructive
pve_reset_qemu_vm	Reset a VM (hard)	read-execute	destructive
pve_migrate_qemu_vm	Migrate a VM to another node	read-execute	destructive
pve_create_qemu_vm	Create a new VM	full	—
pve_delete_qemu_vm	Delete a VM and all its data	full	destructive
pve_update_qemu_config	Update VM configuration	full	destructive, idempotent
pve_clone_qemu_vm	Clone a VM	full	—
pve_create_qemu_snapshot	Create a VM snapshot	full	—
pve_delete_qemu_snapshot	Delete a VM snapshot	full	destructive
pve_rollback_qemu_snapshot	Rollback a VM to a snapshot	full	destructive, idempotent

LXC Containers (18 tools)

Tool	Description	Access	Hints
pve_list_lxc_containers	List all LXC containers on a node	read-only	read-only, idempotent
pve_get_lxc_status	Get current container status	read-only	read-only, idempotent
pve_get_lxc_config	Get container configuration	read-only	read-only, idempotent
pve_get_lxc_rrddata	Get RRD statistics over a time period	read-only	read-only, idempotent
pve_list_lxc_snapshots	List all container snapshots	read-only	read-only, idempotent
pve_start_lxc_container	Start a container	read-execute	destructive
pve_stop_lxc_container	Stop a container (immediate)	read-execute	destructive
pve_shutdown_lxc_container	Gracefully shut down a container	read-execute	destructive
pve_reboot_lxc_container	Reboot a container	read-execute	destructive
pve_suspend_lxc_container	Suspend (freeze) a container	read-execute	destructive
pve_resume_lxc_container	Resume (unfreeze) a container	read-execute	destructive
pve_create_lxc_container	Create a new container	full	—
pve_delete_lxc_container	Delete a container and all its data	full	destructive
pve_update_lxc_config	Update container configuration	full	destructive, idempotent
pve_clone_lxc_container	Clone a container	full	—
pve_create_lxc_snapshot	Create a container snapshot	full	—
pve_delete_lxc_snapshot	Delete a container snapshot	full	destructive
pve_rollback_lxc_snapshot	Rollback a container to a snapshot	full	destructive, idempotent

Storage (9 tools)

Tool	Description	Access	Hints
pve_list_storage	List all configured storage backends	read-only	read-only, idempotent
pve_get_storage_config	Get storage backend configuration	read-only	read-only, idempotent
pve_list_node_storage	List available storage on a node with usage info	read-only	read-only, idempotent
pve_get_storage_status	Get storage status and usage on a node	read-only	read-only, idempotent
pve_list_storage_content	List storage content (images, ISOs, backups)	read-only	read-only, idempotent
pve_pull_oci_image	Pull an OCI container image into a storage's template cache (PVE 9.1+)	read-execute	—
pve_create_storage	Create a new storage backend	full	—
pve_update_storage	Update storage configuration	full	destructive, idempotent
pve_delete_storage	Delete a storage backend	full	destructive

Cluster (13 tools)

Tool	Description	Access	Hints
pve_get_cluster_status	Get cluster status (membership, quorum)	read-only	read-only, idempotent
pve_list_cluster_resources	List all cluster resources with optional type filter	read-only	read-only, idempotent
pve_get_next_vmid	Get the next available VMID	read-only	read-only, idempotent
pve_get_cluster_log	Get recent cluster log entries	read-only	read-only, idempotent
pve_get_cluster_options	Get datacenter options	read-only	read-only, idempotent
pve_list_cluster_backup_info	List guests not covered by backup jobs	read-only	read-only, idempotent
pve_get_cluster_ha_status	Get HA manager status	read-only	read-only, idempotent
pve_list_cluster_replication	List all replication jobs	read-only	read-only, idempotent
pve_bulk_start_guests	Bulk start VMs/containers cluster-wide (PVE 9.1+)	read-execute	destructive
pve_bulk_shutdown_guests	Bulk shutdown VMs/containers cluster-wide (PVE 9.1+)	read-execute	destructive
pve_bulk_suspend_guests	Bulk suspend VMs cluster-wide (PVE 9.1+)	read-execute	destructive
pve_bulk_migrate_guests	Bulk migrate VMs/containers to a target node (PVE 9.1+)	read-execute	destructive
pve_update_cluster_options	Update datacenter options	full	destructive, idempotent

Access Control (10 tools)

Tool	Description	Access	Hints
pve_list_users	List all users	read-only	read-only, idempotent
pve_get_user	Get user details	read-only	read-only, idempotent
pve_list_roles	List all roles and privileges	read-only	read-only, idempotent
pve_list_groups	List all user groups	read-only	read-only, idempotent
pve_list_acls	List all ACL entries	read-only	read-only, idempotent
pve_list_domains	List authentication domains/realms	read-only	read-only, idempotent
pve_create_user	Create a new user	full	—
pve_update_user	Update user properties	full	destructive, idempotent
pve_delete_user	Delete a user	full	destructive
pve_update_acl	Grant or revoke ACL permissions	full	destructive, idempotent

Pools (5 tools)

Tool	Description	Access	Hints
pve_list_pools	List all resource pools	read-only	read-only, idempotent
pve_get_pool	Get pool details and members	read-only	read-only, idempotent
pve_create_pool	Create a resource pool	full	—
pve_update_pool	Update pool members and settings	full	destructive, idempotent
pve_delete_pool	Delete a resource pool	full	destructive

Network (5 tools)

Tool	Description	Access	Hints
pve_list_networks	List all network interfaces on a node	read-only	read-only, idempotent
pve_get_network	Get network interface configuration	read-only	read-only, idempotent
pve_create_network	Create a network interface	full	—
pve_update_network	Update network interface configuration	full	destructive, idempotent
pve_delete_network	Delete a network interface	full	destructive

Firewall (8 tools)

Tool	Description	Access	Hints
pve_get_firewall_options	Get cluster firewall options	read-only	read-only, idempotent
pve_list_firewall_rules	List cluster firewall rules	read-only	read-only, idempotent
pve_list_firewall_aliases	List firewall aliases	read-only	read-only, idempotent
pve_list_firewall_ipsets	List firewall IP sets	read-only	read-only, idempotent
pve_update_firewall_options	Update cluster firewall options	full	destructive, idempotent
pve_create_firewall_rule	Create a firewall rule	full	—
pve_update_firewall_rule	Update a firewall rule	full	destructive, idempotent
pve_delete_firewall_rule	Delete a firewall rule	full	destructive

Backup (5 tools)

Tool	Description	Access	Hints
pve_list_backup_jobs	List all scheduled backup jobs	read-only	read-only, idempotent
pve_get_backup_job	Get backup job configuration	read-only	read-only, idempotent
pve_run_backup	Run an immediate backup (vzdump)	read-execute	—
pve_create_backup_job	Create a scheduled backup job	full	—
pve_delete_backup_job	Delete a scheduled backup job	full	destructive

Tasks (4 tools)

Tool	Description	Access	Hints
pve_list_tasks	List recent tasks on a node	read-only	read-only, idempotent
pve_get_task_status	Get task status by UPID	read-only	read-only, idempotent
pve_get_task_log	Get task log output by UPID	read-only	read-only, idempotent
pve_stop_task	Stop a running task	read-execute	destructive

High Availability (12 tools)

Tool	Description	Access	Hints
pve_list_ha_resources	List all HA-managed resources	read-only	read-only, idempotent
pve_get_ha_resource	Get HA configuration for a resource	read-only	read-only, idempotent
pve_list_ha_rules	List HA rules (node/resource affinity)	read-only	read-only, idempotent
pve_get_ha_rule	Get HA rule configuration	read-only	read-only, idempotent
pve_create_ha_resource	Add a VM/container to HA management	full	—
pve_update_ha_resource	Update HA resource configuration	full	destructive, idempotent
pve_delete_ha_resource	Remove a resource from HA management	full	destructive
pve_create_ha_rule	Create an HA rule	full	—
pve_update_ha_rule	Update an HA rule	full	destructive, idempotent
pve_delete_ha_rule	Delete an HA rule	full	destructive
pve_disarm_ha	Disarm the HA stack for maintenance (PVE 9.2+)	full	destructive, idempotent
pve_arm_ha	Re-arm the HA stack (PVE 9.2+)	full	destructive, idempotent

Note: HA groups are deprecated in PVE 9 in favor of HA rules. The per-service group field was removed from HA status output in PVE 9.1.

Verify It Works

After configuring your MCP client, ask your AI assistant:

"What nodes are in my Proxmox cluster?"

If the connection is working, the assistant will call pve_list_nodes and return your nodes with their current status.

Usage Examples

Once configured, ask your AI tool questions in natural language:

• "List all VMs on node pve1" -- calls pve_list_qemu_vms to show VMs with their status, CPU, and memory usage.

• "What's the status of VM 100?" -- calls pve_get_qemu_status to show real-time resource utilization.

• "Start container 200 on pve1" -- calls pve_start_lxc_container to start the container and returns the task UPID.

• "Create a snapshot of VM 100 called pre-upgrade" -- calls pve_create_qemu_snapshot to create a snapshot before changes.

• "Show me the cluster resources" -- calls pve_list_cluster_resources to show all VMs, containers, storage, and nodes.

• "Migrate VM 100 to node pve2" -- calls pve_migrate_qemu_vm to live-migrate the VM to another node.

• "Shut down VMs 103, 104 and 105 in parallel" -- calls pve_bulk_shutdown_guests to shut down multiple guests cluster-wide in a single request.

Troubleshooting

Connection refused / ECONNREFUSED

Check that PVE_BASE_URL is correct and includes the port (default: 8006). Ensure the PVE host is reachable from where the MCP server is running.

SSL certificate errors

If your PVE instance uses a self-signed certificate, set PVE_VERIFY_SSL=false. This disables TLS verification for all requests.

Tools not showing up

Check your access tier setting. In read-only mode, only 53 tools are registered. In read-execute mode, 75 tools are registered. Use full (or omit PVE_ACCESS_TIER) for all 117 tools. Check PVE_CATEGORIES -- only tools in listed categories are registered. Also verify the server started without errors by checking stderr output.

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (auto-reload)
npm run dev

# Open the MCP Inspector for interactive testing
npm run inspect

License

MIT