SkillAgentSearch skills...

MCP Pve

Manage Proxmox VE through AI assistants

GenerateConvertImprove

Install / Use

/learn @Samik081/MCP Pve
About this skill

Quality Score

0/100

Supported Platforms

Claude Code
Claude Desktop
Cursor

README

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

  • 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

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

Samik081

View profile

View on GitHub
GitHub Stars3
CategoryDevelopment
Updated21h ago
Forks0
Samik081/mcp-pve

Languages

TypeScript

Security Score

90/100

Audited on Apr 2, 2026

No findings