🚀 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

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