Mcp Proxmox

🚀 Proxmox MCP Server (Node.js Edition)

A Node.js-based Model Context Protocol (MCP) server for interacting with Proxmox hypervisors, providing a clean interface for managing nodes, VMs, and containers with configurable permission levels.

🙏 Credits

This project is based on the original Python implementation by canvrno/ProxmoxMCP. This Node.js version maintains the same core functionality while adapting it for JavaScript/Node.js environments and adding configurable permission management.

🔄 Changes from Original

Architecture Changes:

• ✅ Complete rewrite from Python to Node.js
• ✅ Uses @modelcontextprotocol/sdk instead of Python MCP SDK
• ✅ Environment variable configuration instead of JSON config files
• ✅ Simplified dependency management with npm

New Features:

• 🔒 Configurable Permission Levels: PROXMOX_ALLOW_ELEVATED setting for security
• 🛡️ Basic Mode: Safe operations (node listing, VM status) with minimal permissions
• 🔓 Elevated Mode: Advanced features (detailed metrics, command execution) requiring full permissions
• 📝 Better Error Handling: Clear permission warnings and graceful degradation
• 🔧 Auto Environment Loading: Automatically loads .env files from parent directories

🏗️ Built With

• Node.js - JavaScript runtime
• @modelcontextprotocol/sdk - Model Context Protocol SDK for Node.js
• node-fetch - HTTP client for API requests

✨ Features

• 🔒 Configurable Security: Two permission levels for safe operation
• ⚠️ Default: Read-only mode - Safe for production use
• ⚠️ Elevated mode: Enables 49 destructive operations - Use with extreme caution
• 🛠️ Built with the official MCP SDK for Node.js
• 🔐 Secure token-based authentication with Proxmox
• 🖥️ Comprehensive node and VM management
• 💻 VM console command execution (elevated mode)
• 📊 Real-time resource monitoring
• 🎨 Rich markdown-formatted output
• ⚡ Fast Node.js performance
• 🔧 Easy environment-based configuration

https://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b

📦 Installation

Prerequisites

• Node.js 16+ and npm
• Git
• Access to a Proxmox server with API token credentials

Before starting, ensure you have:

• [ ] Node.js and npm installed
• [ ] Proxmox server hostname or IP
• [ ] Proxmox API token (see [API Token Setup](#proxmox-api-token-setup))

Quick Install

1. Clone and set up:

``bash git clone https://github.com/gilby125/mcp-proxmox.git cd mcp-proxmox npm install ``

1. Create .env file in the parent directory of your installation:

```bash # If you cloned to: /home/user/mcp-proxmox # Create .env at: /home/user/.env

cd .. nano .env # or use your preferred editor ```

1. Add your Proxmox configuration to .env:

```bash # Proxmox Configuration (REQUIRED) PROXMOXHOST=your-proxmox-ip-or-hostname PROXMOXUSER=root@pam PROXMOXTOKENNAME=your-token-name PROXMOXTOKENVALUE=your-token-secret-here

# Security Settings (REQUIRED) PROXMOXALLOWELEVATED=false # Set to 'true' for advanced features

# ⚠️ WARNING: Setting PROXMOXALLOWELEVATED=true enables DESTRUCTIVE operations # This allows creating, deleting, modifying VMs/containers, snapshots, backups, etc. # Only enable if you understand the security implications!

# Optional Settings (can be omitted) # PROXMOX_PORT=8006 # Defaults to 8006 ```

Important Notes:

• The .env file MUST be placed in the parent directory of the mcp-proxmox installation
• PROXMOX_TOKEN_VALUE is REQUIRED - there is no default value
• PROXMOX_HOST defaults to 192.168.6.247 if not specified (change this!)
• PROXMOX_TOKEN_NAME defaults to mcpserver if not specified

⚠️ Security Warning:

• PROXMOX_ALLOW_ELEVATED=false is the SAFE default - only read operations allowed
• PROXMOX_ALLOW_ELEVATED=true enables 49 DESTRUCTIVE tools that can:
• Create, delete, start, stop, reboot VMs and containers
• Delete snapshots and backups
• Modify disk configurations, network settings, and resource allocations
• Execute commands inside VMs/containers
• Only set to true if you fully understand and accept these risks

Permission Levels

Basic Mode (PROXMOX_ALLOW_ELEVATED=false):

• List cluster nodes and their status
• List VMs and containers
• View storage pools
• Basic cluster health overview
• Requires minimal API token permissions

Elevated Mode (PROXMOX_ALLOW_ELEVATED=true):

• ⚠️ WARNING: Enables destructive operations - Use with caution!
• All basic features plus:
• Detailed node resource metrics
• VM command execution
• Advanced cluster statistics
• Create/Delete VMs and containers (requires VM.Allocate)
• Start/Stop/Reboot/Shutdown (requires VM.PowerMgmt)
• Snapshot and backup management (requires VM.Snapshot, VM.Backup)
• Disk and network configuration (requires VM.Config)
• Recommended API token permissions: Sys.Audit, VM.Monitor, VM.Console, VM.Allocate, VM.PowerMgmt, VM.Snapshot, VM.Backup, VM.Config, Datastore.Audit, Datastore.Allocate

Verifying Installation

1. Return to the mcp-proxmox directory:

``bash cd mcp-proxmox ``

1. Test the MCP server:

``bash echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node index.js ``

1. Test a basic API call:

``bash echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "proxmox_get_nodes", "arguments": {}}}' | node index.js ``

You should see either:

• A successful list of your Proxmox nodes
• Or an error message - if you see "Could not load .env file", verify the .env file is in the parent directory

⚙️ Configuration

Proxmox API Token Setup

1. Log into your Proxmox web interface
2. Navigate to Datacenter → Permissions → API Tokens
3. Click Add to create a new API token:

• User: Select existing user (e.g., root@pam)
• Token ID: Enter a name (e.g., mcp-server)
• Privilege Separation: Uncheck for full access or leave checked for limited permissions
• Click Add

1. Important: Copy both the Token ID and Secret immediately (secret is only shown once)

• Use Token ID as PROXMOX_TOKEN_NAME
• Use Secret as PROXMOX_TOKEN_VALUE

Permission Requirements:

• Basic Mode: Minimal permissions (usually default user permissions work)
• Elevated Mode: Add permissions for Sys.Audit, VM.Monitor, VM.Console to the user/token

🚀 Running the Server

Direct Execution

node index.js

Claude Desktop Integration

Config File Location

Add the configuration to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: Using External .env File (Recommended)

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-proxmox/index.js"]
    }
  }
}

Important - Environment File Location:

• Replace /absolute/path/to/mcp-proxmox with the actual path to your installation
• The server loads environment variables from ../../.env relative to index.js
• This means: If your installation is at /home/user/mcp-proxmox, place .env at /home/user/.env
• Example directory structure:

`` /home/user/ ├── .env ← Environment file goes here └── mcp-proxmox/ ├── index.js ← Server looks for ../../.env from here ├── package.json └── README.md ``

Option 2: Inline Environment Variables

Alternatively, you can specify environment variables directly in the config:

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-proxmox/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-ip",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "mcp-server",
        "PROXMOX_TOKEN_VALUE": "your-token-secret",
        "PROXMOX_ALLOW_ELEVATED": "false",
        "PROXMOX_PORT": "8006"
      }
    }
  }
}

After adding the configuration:

1. Restart Claude Desktop
2. Verify the server is loaded in Claude Desktop → Settings → Developer → MCP Servers
3. Test by asking Claude: "List my Proxmox VMs"

Other MCP Clients

For Claude Code, MCP Inspector, or other MCP clients, use the stdio transport configuration shown above, adjusting paths as needed for your environment.

🔧 Available Tools

The server provides 55 MCP tools for interacting with Proxmox:

Read-Only Tools (Basic Mode):

• proxmox_get_nodes - List cluster nodes
• proxmox_get_vms - List all VMs and containers
• proxmox_get_vm_status - Get VM details
• proxmox_get_storage - View storage pools
• proxmox_get_cluster_status - Cluster overview

Advanced Tools (Elevated Mode):

• proxmox_get_node_status - Detailed node metrics
• proxmox_execute_vm_command - Run commands in VMs
• proxmox_list_templates - List LXC templates
• proxmox_get_next_vmid - Get next available VM/Container ID
• proxmox_create_lxc - Create LXC container
• proxmox_create_vm - Create QEMU virtual machine
• proxmox_start_lxc / proxmox_start_vm - Start container/VM
• proxmox_stop_lxc / proxmox_stop_vm - Stop container/VM
• proxmox_reboot_lxc / proxmox_reboot_vm - Reboot container/VM
• proxmox_shutdown_lxc / proxmox_shutdown_vm - Gracefully shutdown container/VM
• proxmox_pause_vm / proxmox_resume_vm - Pause/resume VM (QEMU only)
• proxmox_clone_lxc / proxmox_clone_vm - Clone container/VM
• proxmox_resize_lxc / proxmox_resize_vm - Resize container/VM resources
• proxmox_create_snapshot_lxc / proxmox_create_snapshot_vm - Create snapshot
• proxmox_list_snapshots_lxc / proxmox_list_snapshots_vm - List snapshots
• proxmox_rollback_snapshot_lxc / proxmox_rollback_snapshot_vm - Rollback to snapshot
• proxmox_delete_snapshot_lxc / proxmox_delete_snapshot_vm - Delete snapshot
• proxmox_create_backup_lxc / proxmox_create_backup_vm - Create backup
• proxmox_list_backups - List all backups on storage
• proxmox_restore_backup_lxc / proxmox_restore_backup_vm - Restore from backup
• proxmox_delete_backup - Delete backup file
• proxmox_add_disk_vm - Add disk to QEMU VM
• proxmox_add_mountpoint_lxc - Add mount point to LXC container
• proxmox_resize_disk_vm / proxmox_resize_disk_lxc - Resize disk/mount point
• proxmox_remove_disk_vm / proxmox_remove_mountpoint_lxc - Remove disk/mount point
• proxmox_move_disk_vm / proxmox_move_disk_lxc - Move disk between storage
• proxmox_add_network_vm / proxmox_add_network_lxc - Add network interface
• proxmox_update_network_vm / proxmox_update_network_lxc - Update network interface
• proxmox_remove_network_vm / proxmox_remove_network_lxc - Remove network interface
• proxmox_delete_lxc / proxmox_delete_vm - Delete container/VM

---

proxmoxgetnodes

Lists all nodes in the Proxmox cluster with their status and resources.

• Parameters: None
• Example Response:

``` 🖥️ Proxmox Cluster Nodes

🟢 pve1 • Status: online • Uptime: 3d 2h 53m • CPU: 1.8% • Memory: 5.89 GB / 62.21 GB (9.5%) • Load: N/A ```

proxmoxgetnode_status

Get detailed status of a specific node (requires elevated permissions).

• Parameters:
• node (string, required): Name of the node
• Example Response (Basic Mode):

``` ⚠️ Node Status Requires Elevated Permissions

To view detailed node status, set PROXMOX_ALLOW_ELEVATED=true in your .env file and ensure your API token has Sys.Audit permissions.

Current permissions: Basic (node listing only) ```

proxmoxgetvms

List all virtual machines across the cluster with their status.

• Parameters:
• node (string, optional): Filter by specific node
• type (string, optional): VM type filter ('qemu', 'lxc', 'all'), default: 'all'
• Example Response:

``` 💻 Virtual Machines

🟢 📦 docker (ID: 100) • Node: pve1 • Status: running • Type: LXC • Uptime: 5h 40m • CPU: 0.8% • Memory: 7.46 GB / 46.88 GB

🔴 📦 ubuntu1 (ID: 115) • Node: pve1 • Status: stopped • Type: LXC ```

proxmoxgetvm_status

Get detailed status information for a specific VM.

• Parameters:
• node (string, required): Node name where VM is located
• vmid (string, required): VM ID number
• type (string, optional): VM type ('qemu', 'lxc'), default: 'qemu'
• Example Response:

``` 🟢 📦 docker (ID: 100)

• Node: pve1 • Status: running • Type: LXC • Uptime: 5h 42m • CPU Usage: 0.8% • Memory: 7.47 GB / 46.88 GB (15.9%) • Disk Read: 19.74 GB • Disk Write: 21.71 GB • Network In: 1.32 GB • Network Out: 216.56 MB ```

proxmoxgetstorage

List all storage pools and their usage across the cluster.

• Parameters:
• node (string, optional): Filter by specific node
• Example Response:

``` 💾 Storage Pools

🟢 local • Node: pve1 • Type: dir • Content: vztmpl,iso,backup • Usage: 19.58 GB / 93.93 GB (20.8%) • Status: Enabled

🟢 zfs • Node: pve1 • Type: zfspool • Content: rootdir,images • Usage: 87.33 MB / 899.25 GB (0.0%) • Status: Enabled ```

proxmoxgetcluster_status

Get overall cluster status including nodes and resource usage.

• Parameters: None
• Example Response (Basic Mode):

``` 🏗️ Proxmox Cluster Status

Cluster Health: 🟢 Healthy Nodes: 1/1 online

⚠️ Limited Information: Resource usage requires elevated permissions

Node Details: 🟢 pve1 - online ```

proxmoxexecutevm_command

Execute a shell command on a virtual machine via Proxmox API (requires elevated permissions).

• Parameters:
• node (string, required): Node name where VM is located
• vmid (string, required): VM ID number
• command (string, required): Shell command to execute
• type (string, optional): VM type ('qemu', 'lxc'), default: 'qemu'
• Example Response (Basic Mode):

``` ⚠️ VM Command Execution Requires Elevated Permissions

To execute commands on VMs, set PROXMOX_ALLOW_ELEVATED=true in your .env file and ensure your API token has appropriate VM permissions.

Current permissions: Basic (VM listing only) Requested command: uptime ```

• Requirements (Elevated Mode):
• VM must be running
• For QEMU: QEMU Guest Agent must be installed and running
• For LXC: Direct execution via Proxmox API
• Appropriate API token permissions

proxmoxlisttemplates

List available LXC container templates on a storage.

• Parameters:
• node (string, required): Node name
• storage (string, optional): Storage name, default: 'local'
• Example Response:

``` 📦 Available LXC Templates

• local:vztmpl/debian-12-standard12.2-1amd64.tar.gz Size: 129.50 MB

• local:vztmpl/ubuntu-22.04-standard22.04-1amd64.tar.gz Size: 142.30 MB ```

• Requirements:
• API token with Datastore.Audit or Datastore.AllocateSpace permissions

proxmoxcreatelxc

Create a new LXC container (requires elevated permissions).

• Parameters:
• node (string, required): Node name where container will be created
• vmid (string, required): VM ID number (must be unique)
• ostemplate (string, required): OS template path (e.g., local:vztmpl/debian-12-standard_12.2-1_amd64.tar.gz)
• hostname (string, optional): Container hostname
• password (string, optional): Root password, default: 'proxmox'
• memory (number, option

…

Source & license

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

• Author: gilby125
• Source: gilby125/mcp-proxmox
• License: MIT

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