Proxmox MCP Server

Model Context Protocol (MCP) server for Proxmox Virtual Environment

English | 한국어

A comprehensive MCP server providing 92 tools for managing Proxmox Virtual Environment, including QEMU VMs and LXC containers.

Credits & Background

This project is a TypeScript rewrite of mcp-proxmox-server, which itself was a Node.js port of the original Python implementation by canvrno/ProxmoxMCP.

What Changed

Architecture:

• 3,147-line single-file monolith → modular TypeScript across 110+ source files
• No type safety → strict TypeScript with noUncheckedIndexedAccess
• Hand-written JSON Schema → Zod schemas with automatic JSON Schema generation
• Giant switch statement (55 cases) → tool registry with handler/schema pairs

Quality:

• 0 tests → 1,134 tests
• No input validation → Zod runtime validation on every tool call
• Implicit error handling → structured MCP error responses with context
• No permission checks → two-tier permission model (basic / elevated)

Developer Experience:

• npx @bldg-7/proxmox-mcp just works
• All 92 tool descriptions exposed via MCP ListTools
• Rate limiter middleware included
• Pino structured logging instead of console.log

Features

• 92 comprehensive tools for Proxmox management
• Full TypeScript implementation with strict type safety
• Support for both QEMU VMs and LXC containers
• Secure authentication (API token)
• Flexible SSL modes (strict, verify, insecure)
• Permission-based access control (basic vs elevated operations)
• Comprehensive error handling with structured responses
• Built on MCP SDK 1.25.3

Installation

npm install @bldg-7/proxmox-mcp
# or
pnpm add @bldg-7/proxmox-mcp
# or
yarn add @bldg-7/proxmox-mcp

Configuration

Environment Variables

Set the following environment variables before starting the server:

Variable	Required	Description	Default
PROXMOX_HOST	Yes	Proxmox server hostname or IP address	-
PROXMOX_USER	No	Username with realm (e.g., root@pam)	root@pam
PROXMOX_TOKEN_NAME	Yes	API token name	-
PROXMOX_TOKEN_VALUE	Yes	API token value	-
PROXMOX_SSL_MODE	No	SSL verification mode	strict
PROXMOX_ALLOW_ELEVATED	No	Allow elevated operations	false
PROXMOX_PORT	No	Proxmox API port	8006
PROXMOX_ALLOW_UNSAFE_COMMANDS	No	Allow shell special characters in exec commands	false
PROXMOX_SSH_ENABLED	No	Enable SSH-based LXC exec	false
PROXMOX_SSH_HOST	No	SSH host (falls back to PROXMOX_HOST)	-
PROXMOX_SSH_PORT	No	SSH port	22
PROXMOX_SSH_USER	No	SSH username	root
PROXMOX_SSH_KEY_PATH	When SSH enabled	Path to SSH private key	-
PROXMOX_SSH_NODE	When SSH enabled	Proxmox node name reachable via SSH	-
PROXMOX_SSH_HOST_KEY_FINGERPRINT	No	Host key fingerprint for verification	-

SSL Modes

• strict: Full SSL certificate verification (recommended for production)
• verify: Verify SSL but allow self-signed certificates
• insecure: No SSL verification (development only, not recommended)

Permission Model

The server implements a two-tier permission model:

• Basic operations: Read-only operations (list, get, status) - always allowed
• Elevated operations: Create, modify, delete operations - require PROXMOX_ALLOW_ELEVATED=true

This prevents accidental destructive operations and provides an additional safety layer.

Usage

Starting the Server

# With environment variables
export PROXMOX_HOST=pve.example.com
export PROXMOX_TOKEN_NAME=mytoken
export PROXMOX_TOKEN_VALUE=abc123-def456-ghi789
export PROXMOX_SSL_MODE=verify
export PROXMOX_ALLOW_ELEVATED=true

npx @bldg-7/proxmox-mcp

Using with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": ["-y", "@bldg-7/proxmox-mcp"],
      "env": {
        "PROXMOX_HOST": "pve.example.com",
        "PROXMOX_TOKEN_NAME": "mytoken",
        "PROXMOX_TOKEN_VALUE": "abc123-def456-ghi789",
        "PROXMOX_SSL_MODE": "verify",
        "PROXMOX_ALLOW_ELEVATED": "true"
      }
    }
  }
}

Available Tools

This server provides 92 comprehensive tools for Proxmox management:

Category	Tools	Permission
Node Management	14	Mixed
Guest (VM/LXC)	23	Mixed
Guest Creation	2	Elevated 🔒
QEMU Agent	7	Elevated 🔒
Cluster Operations	5	Mixed
Cluster Firewall	6	Mixed
High Availability	2	Mixed
Storage	3	Mixed
SDN Networking	4	Mixed
Access Control	7	Mixed
Ceph	6	Mixed
Console Access	3	Elevated 🔒
Backup	1	Mixed
VM Disks	1	Elevated 🔒
LXC Mount Points	1	Elevated 🔒
LXC Exec	1	Elevated 🔒
Cloud-Init	1	Mixed
Certificates	1	Mixed
ACME	3	Mixed
Notifications	1	Mixed
Total	92

📖 Full Tools Reference →

Agent Skills

This package includes Agent Skills - AI-optimized documentation that teaches agents how to use Proxmox MCP tools and operational best practices. Skills follow the agentskills.io open standard and work across multiple AI agent platforms.

Available Skills

Skill	Description	Tools/Topics
proxmox-mcp-tools	Complete MCP tool reference for Proxmox VE	92 tools across 14 domains (VMs, LXC, cluster, storage, networking, Ceph, certificates, ACME, notifications)
proxmox-admin	Operational expertise for Proxmox infrastructure	VM lifecycle, storage management, HA configuration, troubleshooting

Installation

For Agent Skills Standard (Claude Code, OpenCode, Cursor, Codex, Gemini CLI, VS Code):

npx skills add Bldg-7/proxmox-mcp

For Claude Code Plugin:

/plugin marketplace add Bldg-7/proxmox-mcp

Supported Agents

• Claude Code - Anthropic's official CLI
• OpenCode - Open-source Claude Code alternative
• Cursor - AI-powered code editor
• Codex - GitHub Copilot CLI
• Gemini CLI - Google's AI assistant
• VS Code - With agent skills extensions

Skills provide progressive disclosure: metadata (~100 tokens) → instructions (<5000 tokens) → detailed references (on demand).

How Skills Work

Once installed, skills are automatically loaded into the agent's context. The agent learns Proxmox tool usage, workflows, and best practices — so you can give natural language instructions and the agent translates them into the right MCP tool calls.

Example — Creating a VM (agent uses proxmox-mcp-tools skill):

You: "Create an Ubuntu VM with 4 cores, 8GB RAM, and 50GB disk on pve1"

Agent knows the workflow from the skill:
  1. proxmox_get_next_vmid        → gets available VM ID (e.g., 105)
  2. proxmox_create_vm            → creates VM 105 with 4 cores, 8GB RAM
  3. proxmox_vm_disk              → attaches 50GB virtio disk (action: 'add')
  4. proxmox_guest_network        → adds network interface on vmbr0 (action: 'add', type: 'vm')
  5. proxmox_guest_start          → powers on the VM (type: 'vm')

Example — Setting up HA (agent uses proxmox-admin skill):

You: "Make VM 100 highly available"

Agent knows the operational playbook:
  1. proxmox_ha_group             → checks existing HA groups (action: 'list')
  2. proxmox_ha_resource          → adds VM 100 to HA with priority (action: 'create')
  3. proxmox_ha_resource          → verifies HA is active (action: 'status')

Example — Troubleshooting (agent uses both skills together):

You: "VM 100 won't start, help me figure out why"

Agent combines tool knowledge + operational expertise:
  1. proxmox_guest_status         → checks current state (type: 'vm')
  2. proxmox_guest_config         → reviews configuration (action: 'get', type: 'vm')
  3. proxmox_node                 → checks node resource availability (action: 'status')
  4. proxmox_node_task            → finds recent failed tasks (action: 'list')
  → Diagnoses: "Node pve1 has insufficient memory. VM requires 8GB but only 2GB free."
  → Suggests: resize VM memory, migrate to another node, or free resources

Skill Contents

proxmox-mcp-tools — Tool Reference:

• 92 tools organized into 14 domains (VMs, LXC, cluster, storage, networking, Ceph, access control, pools, certificates, ACME, notifications)
• Parameters, types, and descriptions for every tool
• Permission levels (basic vs elevated 🔒)
• Common workflow patterns (create VM, backup/restore, clone, migrate)

proxmox-admin — Operational Expertise:

• VM & LXC lifecycle playbooks (create → configure → monitor → backup → decommission)
• Storage management strategies (Ceph, NFS, LVM, ZFS)
• HA configuration and failover procedures
• Troubleshooting guides for common API quirks
• Security best practices (permission model, token management)
• Performance monitoring and optimization

SubAgents

This package includes SubAgents - specialized AI agents for executing domain-specific Proxmox operations. While Skills provide knowledge ("here are the tools and how to use them"), SubAgents provide action ("I'll do this for you"). SubAgents automatically load the relevant skills and execute operations using MCP tools.

Available SubAgents

SubAgent	Domain	Description
vm-manager	QEMU VMs	VM lifecycle management (create, configure, start/stop, snapshots, backups, cloning, templates)
lxc-manager	LXC Containers	Container lifecycle management (create, configure, mount points, snapshots, backups, cloning)
cluster-admin	Cluster Operations	High availability, VM/LXC migration, replication jobs, cluster firewall, cluster backup jobs
storage-admin	Storage Infrastructure	Storage backends (NFS, iSCSI, Ceph), ISO/template management, backup pruning, disk operations
network-admin	Network Infrastructure	SDN (VNets, zones, controllers, subnets), node network interfaces, DNS configuration
access-admin	Access Control	Users, groups, roles, ACLs, authentication domains (PAM, LDAP, AD)
monitor	Monitoring	Read-only health checks, status monitoring, log analysis, task tracking (delegates actions to other agents)

How SubAgents Work

SubAgents use auto-delegation in Claude Code and compatible platforms:

1. User makes request: "Create a new Ubuntu VM with 4 cores and 8GB RAM"
2. Claude analyzes request: Matches request to vm-manager agent based on example blocks
3. Auto-delegates: Invokes vm-manager agent with full context
4. Agent executes: vm-manager loads skills, calls MCP tools, completes operation
5. Returns result: Structured response with operation details

Prerequisites

• MCP Server: The Proxmox MCP server must be connected and configured
• Skills: SubAgents automatically load proxmox-mcp-tools and proxmox-admin skills
• Permissions: Elevated operations require PROXMOX_ALLOW_ELEVATED=true in MCP server config

Installation

SubAgents are included when you install the plugin:

For Claude Code Plugin:

/plugin marketplace add Bldg-7/proxmox-mcp

For Agent Skills Standard (if supported):

npx skills add Bldg-7/proxmox-mcp

Usage Examples

Create a VM (auto-delegates to vm-manager):

User: "Create a new Ubuntu VM with 4 cores, 8GB RAM, and a 50GB disk on node pve1"
→ vm-manager executes: get next VMID → create VM → add disk → add network → start

Enable HA (auto-delegates to cluster-admin):

User: "Enable high availability for VM 100 with priority 100"
→ cluster-admin executes: check HA config → add HA resource → verify

Monitor cluster (auto-delegates to monitor):

User: "Show me the current cluster status and any issues"
→ monitor executes: get cluster status → get HA status → get nodes → report

Agent Domain Boundaries

Each SubAgent has clear responsibilities to avoid overlap:

• vm-manager: Only QEMU VMs (not LXC). Delegates cluster ops to cluster-admin.
• lxc-manager: Only LXC containers (not VMs). Delegates cluster ops to cluster-admin.
• cluster-admin: Cluster-wide operations (HA, firewall aliases/ipsets, cluster config, notifications). Delegates per-VM/LXC ops to respective managers.
• storage-admin: Storage infrastructure, certificate management, ACME configuration, advanced disk operations. Delegates VM disk operations to vm-manager.
• network-admin: Network infrastructure only. Delegates per-VM/LXC NICs to respective managers.
• access-admin: Access control including API token management. No delegation to other agents.
• monitor: Read-only monitoring including node metrics/RRD data. Delegates ALL actions to appropriate agents.

Error Handling

All tools return structured responses following the MCP protocol:

Success Response

{
  "content": [
    {
      "type": "text",
      "text": "✅ Operation completed successfully\n\n• Details here..."
    }
  ],
  "isError": false
}

Error Response

{
  "content": [
    {
      "type": "text",
      "text": "❌ Error: Operation failed\n\nReason: Detailed error message"
    }
  ],
  "isError": true
}

Permission Denied

{
  "content": [
    {
      "type": "text",
      "text": "🚫 Permission Denied: Operation requires elevated permissions\n\nSet PROXMOX_ALLOW_ELEVATED=true to enable this operation."
    }
  ],
  "isError": true
}

Troubleshooting

Connection Issues

Problem: ECONNREFUSED or connection timeout

Solutions:

• Verify PROXMOX_HOST is correct and reachable
• Check PROXMOX_PORT (default: 8006)
• Ensure firewall allows connections to Proxmox API port
• Try PROXMOX_SSL_MODE=insecure for testing (not recommended for production)

Authentication Errors

Problem: 401 Unauthorized or authentication failed

Solutions:

• Verify PROXMOX_USER includes realm if set (e.g., root@pam, not just root)
• Verify PROXMOX_TOKEN_NAME and PROXMOX_TOKEN_VALUE are valid
• Ensure API token has sufficient permissions in Proxmox

SSL Certificate Errors

Problem: UNABLE_TO_VERIFY_LEAF_SIGNATURE or SSL errors

Solutions:

• Use PROXMOX_SSL_MODE=verify for self-signed certificates
• Use PROXMOX_SSL_MODE=insecure for development (not recommended for production)
• Install proper SSL certificates on Proxmox server for production use

Permission Denied Errors

Problem: 🚫 Permission Denied for operations

Solutions:

• Set PROXMOX_ALLOW_ELEVATED=true to enable elevated operations
• Review which operations require elevated permissions (marked with 🔒)
• Ensure this is intentional - elevated operations can modify/delete resources

Development

Building from Source

git clone https://github.com/Bldg-7/proxmox-mcp.git
cd proxmox-mcp
pnpm install
pnpm build

Running Tests

pnpm test              # Run tests once
pnpm test:watch        # Run tests in watch mode
pnpm test:coverage     # Run tests with coverage report

Type Checking

pnpm typecheck         # Type check without emitting files

Linting

pnpm lint              # Run ESLint

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built with Model Context Protocol SDK
• Powered by Proxmox Virtual Environment

---

Legend: 🔒 = Requires elevated permissions (PROXMOX_ALLOW_ELEVATED=true)