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