mcp-proxmox

gilby125/mcp-proxmox

3.3

If you are the rightful owner of mcp-proxmox and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Node.js-based Model Context Protocol (MCP) server for managing Proxmox hypervisors with configurable permissions.

šŸš€ 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

āœØ Features

  • šŸ”’ Configurable Security: Two permission levels for safe operation
  • šŸ› ļø 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)

Quick Install

  1. Clone and set up:

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

  2. Create .env file with your Proxmox configuration:

    # Proxmox Configuration
PROXMOX_HOST=192.168.1.100
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=mcp-server
PROXMOX_TOKEN_VALUE=your-token-value-here
PROXMOX_ALLOW_ELEVATED=false  # Set to 'true' for advanced features

    Note: PROXMOX_PORT defaults to 8006 and can be omitted unless using a custom port.

Permission Levels

Basic Mode (PROXMOX_ALLOW_ELEVATED=false):

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

Elevated Mode (PROXMOX_ALLOW_ELEVATED=true):

  • All basic features plus:
  • Detailed node resource metrics
  • VM command execution
  • Advanced cluster statistics
  • Requires API token with Sys.Audit, VM.Monitor, VM.Console permissions

Verifying Installation

  1. Test the MCP server:

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

  2. Test a basic API call:

    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 a connection/permission error with helpful guidance

āš™ļø 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
  4. 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

MCP Client Integration

For Claude Code or other MCP clients, add this to your MCP configuration:

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

Important:

  • Replace /absolute/path/to/mcp-proxmox with the actual path to your installation
  • The server automatically loads environment variables from .env files
  • Ensure the .env file is in the same directory as index.js or a parent directory

šŸ”§ Available Tools

The server provides the following MCP tools for interacting with Proxmox:

proxmox_get_nodes

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

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

proxmox_get_vms

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

proxmox_get_vm_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

proxmox_get_storage

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

proxmox_get_cluster_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

proxmox_execute_vm_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

šŸ‘Øā€šŸ’» Development

Development Commands

# Install dependencies
npm install

# Run server (production)
npm start
# or
node index.js

# Run server with auto-reload (development)
npm run dev

# Test MCP server functionality
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node index.js

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

Development Notes

  • The server loads environment variables from .env files automatically
  • Use npm run dev for development with auto-reload on file changes
  • All API calls require a proper .env configuration
  • Check the server logs for connection and permission issues

šŸ“ Project Structure

mcp-proxmox/
ā”œā”€ā”€ index.js                  # Main MCP server implementation
ā”œā”€ā”€ package.json             # Node.js dependencies and scripts
ā”œā”€ā”€ package-lock.json        # Dependency lock file
ā”œā”€ā”€ .env                     # Environment configuration (not in git)
ā”œā”€ā”€ node_modules/            # Dependencies (not in git)
ā””ā”€ā”€ README.md               # This documentation

šŸ“„ License

MIT License