Mcp Proxmox

@gilby125on 16 days ago

1 MIT

FreeCommunity

AI Systems

MCP server for Proxmox virtualization management with configurable permissions

What is Mcp Proxmox

mcp-proxmox is a Node.js-based Model Context Protocol (MCP) server designed for managing Proxmox virtualization environments. It provides a clean interface for handling nodes, virtual machines (VMs), and containers with configurable permission levels.

Use cases

Use cases for mcp-proxmox include managing multiple Proxmox nodes, executing VM console commands, monitoring resource usage in real-time, and ensuring secure access control for different user roles within a virtualization environment.

How to use

To use mcp-proxmox, install the server using npm, configure the environment variables for your Proxmox setup, and run the server. You can then interact with the Proxmox hypervisors through the provided API, utilizing either basic or elevated permission modes based on your needs.

Key features

Key features include configurable permission levels for security, basic and elevated operation modes, secure token-based authentication, comprehensive management of nodes and VMs, real-time resource monitoring, and easy environment-based configuration.

Where to use

mcp-proxmox is ideal for use in data centers, cloud service providers, and enterprises that utilize Proxmox for virtualization management, requiring a secure and efficient way to manage resources and permissions.

Overview

What is Mcp Proxmox

Use cases

How to use

Key features

Where to use

Content

🚀 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
🛠️ 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

Clone and set up:

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

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

Test the MCP server:

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

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

Log into your Proxmox web interface
Navigate to Datacenter → Permissions → API Tokens
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
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

Mcp Proxmox

What is Mcp Proxmox

Use cases

How to use

Key features

Where to use

Overview

What is Mcp Proxmox

Use cases

How to use

Key features

Where to use

Content

🚀 Proxmox MCP Server (Node.js Edition)

🙏 Credits

🔄 Changes from Original

🏗️ Built With

✨ Features

📦 Installation

⚙️ Configuration

🚀 Running the Server

🔧 Available Tools

👨‍💻 Development

📁 Project Structure

📄 License

Tools

Comments