# Mcp Pve

> Manage Proxmox VE through AI assistants

- **Type:** MCP server
- **Install:** `agentstack add mcp-samik081-mcp-pve`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Samik081](https://agentstack.voostack.com/s/samik081)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.4.7
- **License:** MIT
- **Upstream author:** [Samik081](https://github.com/Samik081)
- **Source:** https://github.com/Samik081/mcp-pve

## Install

```sh
agentstack add mcp-samik081-mcp-pve
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](https://www.npmjs.com/package/@samik081/mcp-pve)
[](https://ghcr.io/samik081/mcp-pve)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)

# MCP PVE

MCP server for [Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment/overview). 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](https://ghcr.io/samik081/mcp-pve)
- **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).

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 (8 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_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 (9 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_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_ba

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Samik081](https://github.com/Samik081)
- **Source:** [Samik081/mcp-pve](https://github.com/Samik081/mcp-pve)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.4.7 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.4.7** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-samik081-mcp-pve
- Seller: https://agentstack.voostack.com/s/samik081
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.