Files

gilby125 f585111116 Remove Claude Code reference from README

- Clean up dependencies section
- Keep focus on core technical requirements

2025-06-05 14:44:43 -05:00

8.5 KiB

Raw Blame History

🚀 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_PORT=8006
PROXMOX_ALLOW_ELEVATED=false  # Set to 'true' for advanced features

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
Create a new API token:
- Select a user (e.g., root@pam)
- Enter a token ID (e.g., "mcp-token")
- Uncheck "Privilege Separation" if you want full access
- Save and copy both the token ID and secret

🚀 Running the Server

Direct Execution

node index.js

Claude Code Integration

Add this to your Claude Code MCP configuration:

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

The server will automatically load environment variables from .env files in the current directory or parent directories.

🔧 Available Tools

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

proxmox_get_nodes

Lists all nodes in the Proxmox cluster.

Parameters: None

Example Response:

🖥️ Proxmox Nodes

🖥️ pve-compute-01
  • Status: ONLINE
  • Uptime: ⏳ 156d 12h
  • CPU Cores: 64
  • Memory: 186.5 GB / 512.0 GB (36.4%)

🖥️ pve-compute-02
  • Status: ONLINE
  • Uptime: ⏳ 156d 11h
  • CPU Cores: 64
  • Memory: 201.3 GB / 512.0 GB (39.3%)

proxmox_get_node_status

Get detailed status of a specific node.

Parameters:
- node (string, required): Name of the node

Example Response:

🖥️ Node: pve-compute-01
  • Status: ONLINE
  • Uptime: ⏳ 156d 12h
  • CPU Usage: 42.3%
  • CPU Cores: 64 (AMD EPYC 7763)
  • Memory: 186.5 GB / 512.0 GB (36.4%)
  • Network: ⬆️ 12.8 GB/s ⬇️ 9.2 GB/s
  • Temperature: 38°C

proxmox_get_vms

List all VMs across the cluster.

Parameters: None

Example Response:

🗃️ Virtual Machines

🗃️ prod-db-master (ID: 100)
  • Status: RUNNING
  • Node: pve-compute-01
  • CPU Cores: 16
  • Memory: 92.3 GB / 128.0 GB (72.1%)

🗃️ prod-web-01 (ID: 102)
  • Status: RUNNING
  • Node: pve-compute-01
  • CPU Cores: 8
  • Memory: 12.8 GB / 32.0 GB (40.0%)

proxmox_get_storage

List available storage.

Parameters: None

Example Response:

💾 Storage Pools

💾 ceph-prod
  • Status: ONLINE
  • Type: rbd
  • Usage: 12.8 TB / 20.0 TB (64.0%)
  • IOPS: ⬆️ 15.2k ⬇️ 12.8k

💾 local-zfs
  • Status: ONLINE
  • Type: zfspool
  • Usage: 3.2 TB / 8.0 TB (40.0%)
  • IOPS: ⬆️ 42.8k ⬇️ 35.6k

proxmox_get_cluster_status

Get overall cluster status.

Parameters: None

Example Response:

⚙️ Proxmox Cluster

  • Name: enterprise-cloud
  • Status: HEALTHY
  • Quorum: OK
  • Nodes: 4 ONLINE
  • Version: 8.1.3
  • HA Status: ACTIVE
  • Resources:
    - Total CPU Cores: 192
    - Total Memory: 1536 GB
    - Total Storage: 70 TB
  • Workload:
    - Running VMs: 7
    - Total VMs: 8
    - Average CPU Usage: 38.6%
    - Average Memory Usage: 42.8%

proxmox_execute_vm_command

Execute a command in a VM's console using QEMU Guest Agent.

Parameters:
- node (string, required): Name of the node where VM is running
- vmid (string, required): ID of the VM
- command (string, required): Command to execute

Example Response:

🔧 Console Command Result
  • Status: SUCCESS
  • Command: systemctl status nginx
  • Node: pve-compute-01
  • VM: prod-web-01 (ID: 102)

Output:
● nginx.service - A high performance web server and a reverse proxy server
   Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2025-02-18 15:23:45 UTC; 2 months 3 days ago

Requirements:
- VM must be running
- QEMU Guest Agent must be installed and running in the VM
- Command execution permissions must be enabled in the Guest Agent
Error Handling:
- Returns error if VM is not running
- Returns error if VM is not found
- Returns error if command execution fails
- Includes command output even if command returns non-zero exit code

👨‍💻 Development

Development commands:

Install dependencies: npm install
Run server: npm start
Test server: echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node index.js

📁 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

8.5 KiB Raw Blame History

🚀 Proxmox MCP Server (Node.js Edition)

🙏 Credits

🔄 Changes from Original

🏗️ Built With

✨ Features

📦 Installation

Prerequisites

Quick Install

Permission Levels

Verifying Installation

⚙️ Configuration

Proxmox API Token Setup

🚀 Running the Server

Direct Execution

Claude Code Integration

🔧 Available Tools

proxmox_get_nodes

proxmox_get_node_status

proxmox_get_vms

proxmox_get_storage

proxmox_get_cluster_status

proxmox_execute_vm_command

👨‍💻 Development

📁 Project Structure

📄 License

8.5 KiB

Raw Blame History