gilby125/mcp-proxmox
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
- 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
- User: Select existing user (e.g.,
- 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
- Use Token ID as
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 asindex.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 nodetype
(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 locatedvmid
(string, required): VM ID numbertype
(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 locatedvmid
(string, required): VM ID numbercommand
(string, required): Shell command to executetype
(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