Manage Proxmox VE through AI assistants
Valid MCP server (1 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry. Trust signals: trusted author (4/4 approved).
4 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: PVE_BASE_URL
Environment variable: PVE_TOKEN_ID
Environment variable: PVE_TOKEN_SECRET
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-samik081-mcp-pve": {
"env": {
"PVE_BASE_URL": "your-pve-base-url-here",
"PVE_TOKEN_ID": "your-pve-token-id-here",
"PVE_TOKEN_SECRET": "your-pve-token-secret-here"
},
"args": [
"-y",
"@samik081/mcp-pve"
],
"command": "npx"
}
}
}From the project's GitHub README.
MCP server for Proxmox VE. Manage virtual machines, containers, storage, networking, and clusters through natural language in Cursor, Claude Code, and Claude Desktop.
read-only, read-execute, full) for granular controlPVE_CATEGORIES to expose only the tools you needfetch (Node 18+)PVE_VERIFY_SSL=falselinux/amd64 and linux/arm64 on GHCRMCP_TRANSPORT=http) using the Streamable HTTP protocolTested with Proxmox VE 9.0.10.
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.
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.
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"
}
}
}
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:
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.
| 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.
nodes, qemu, lxc, storage, cluster, access, pools, network, firewall, backup, tasks, ha
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).
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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.
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.
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.
If your PVE instance uses a self-signed certificate, set PVE_VERIFY_SSL=false. This disables TLS verification for all requests.
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.
# 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
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally
by mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.