io.github.Samik081/mcp-pve

Official

by Samik081 · TypeScript

Proxmox VE MCP Server

Manage Proxmox VE through AI assistants

Control Proxmox VE infrastructure through AI assistants.

Topics

claude-codecoding-assistantmcpmcp-servermodel-context-protocolproxmoxproxmox-vepve

README.md20 KBView on GitHub

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

105 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.0.10.

Quick Start

Run the server directly with npx:

bash

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):

bash

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:

bash

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):

bash

# 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):

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):

json

{
  "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):

json

{
  "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)	105	Read, execute, and write -- full control
`read-execute`	68	Read and execute -- no resource creation/deletion
`read-only`	51	Read only -- safe for exploration, no state changes

Tier details:

full: All 105 tools. Includes creating/deleting VMs, containers, storage, users, firewall rules, and more.
read-execute: 68 tools. All read tools plus power actions (start, stop, migrate), backup execution, and task management.
read-only: 51 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 105 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).

<details> <summary>Nodes (8 tools)</summary>

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

</details> <details> <summary>QEMU Virtual Machines (20 tools)</summary>

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

</details> <details> <summary>LXC Containers (18 tools)</summary>

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

</details> <details> <summary>Storage (8 tools)</summary>

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_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

</details> <details> <summary>Cluster (9 tools)</summary>

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_update_cluster_options`	Update datacenter options	full	destructive, idempotent

</details> <details> <summary>Access Control (10 tools)</summary>

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

</details> <details> <summary>Pools (5 tools)</summary>

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

</details> <details> <summary>Network (5 tools)</summary>

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

</details> <details> <summary>Firewall (8 tools)</summary>

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

</details> <details> <summary>Backup (5 tools)</summary>

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

</details> <details> <summary>Tasks (4 tools)</summary>

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

</details> <details> <summary>High Availability (5 tools)</summary>

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_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

</details>

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.

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 51 tools are registered. In read-execute mode, 68 tools are registered. Use full (or omit PVE_ACCESS_TIER) for all 105 tools. Check PVE_CATEGORIES -- only tools in listed categories are registered. Also verify the server started without errors by checking stderr output.

Development

bash

# 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

Install

Configuration

Environment variables

PVE_BASE_URLrequired

URL of the Proxmox VE instance (e.g. https://pve.example.com:8006)

PVE_TOKEN_IDrequiredsecret

Proxmox VE API token ID (e.g. user@pam!token-name)

PVE_TOKEN_SECRETrequiredsecret

Proxmox VE API token secret

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-pve": {
      "command": "npx",
      "args": [
        "-y",
        "@samik081/mcp-pve@0.6.1"
      ],
      "env": {
        "PVE_BASE_URL": "<YOUR_PVE_BASE_URL>",
        "PVE_TOKEN_ID": "<YOUR_PVE_TOKEN_ID>",
        "PVE_TOKEN_SECRET": "<YOUR_PVE_TOKEN_SECRET>"
      }
    }
  }
}