MCP Server for Proxmox VE

A Model Context Protocol (MCP) server for Proxmox Virtual Environment that enables AI assistants to manage virtual machines, containers, nodes, and resources through natural language interactions.

🚀 Features

Core Proxmox Management

• Node Management: List and monitor Proxmox cluster nodes

• VM Operations: Start, stop, and monitor virtual machines

• Container Management: Manage LXC containers

• Status Monitoring: Real-time status information for nodes, VMs, and containers

🆕 Full Container Provisioning (v0.2.0)

• Automated Provisioning: Create containers with full infrastructure automation

• Netbox IPAM Integration: Automatic IP and VM registration

• NPM Reverse Proxy: Automatic proxy host creation with SSL

• DNS Registration: Automatic AdGuard Home DNS entries

• Monitoring Setup: Automatic node_exporter and promtail installation

• Backup Configuration: Automatic Proxmox backup scheduling

• Template Stacks: Pre-configured templates (media, dev, monitoring)

• CTID Auto-Assignment: Intelligent CTID assignment by function

Infrastructure

• Secure Authentication: Support for both password and API token authentication

• Multi-Node Support: Works with single nodes or full Proxmox clusters

• Natural Language: Deploy infrastructure by talking to AI

Related MCP server: proxmox-mcp

📋 Prerequisites

• Node.js 18.0.0 or higher

• Proxmox VE 7.0+ with API access

• Valid Proxmox credentials (username/password or API token)

🛠️ Installation

From Source

git clone https://github.com/heybearc/mcp-server-proxmox.git
cd mcp-server-proxmox
npm install
npm run build

From NPM (Coming Soon)

npm install -g mcp-server-proxmox

⚙️ Configuration

Environment Variables

Create a .env file or set the following environment variables:

# Proxmox Server Configuration
PROXMOX_HOST=your-proxmox-host.com
PROXMOX_PORT=8006
PROXMOX_USERNAME=root
PROXMOX_REALM=pam

# Authentication Method 1: Password
PROXMOX_PASSWORD=your-password

# Authentication Method 2: API Token (Recommended)
PROXMOX_TOKEN=your-api-token
PROXMOX_TOKEN_NAME=your-token-name

# SSL Configuration
PROXMOX_VERIFY_SSL=true

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/path/to/mcp-server-proxmox/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-host.com",
        "PROXMOX_USERNAME": "root",
        "PROXMOX_TOKEN": "your-api-token",
        "PROXMOX_TOKEN_NAME": "your-token-name"
      }
    }
  }
}

Other MCP Clients

Refer to your MCP client's documentation for server configuration.

🔧 Available Tools

Basic Operations

🆕 Provisioning Tools (v0.2.0)

💡 Usage Examples

With AI Assistant

Basic Operations:

"Show me all VMs on my Proxmox cluster"
"Start VM 100 on node pve1"
"What's the status of my Proxmox nodes?"
"List all containers on node pve2"

🆕 Provisioning (v0.2.0):

"Create a new media server container with 4GB RAM at 10.92.3.15"
"Deploy a Scrypted NVR container with domain scrypted.cloudigan.net"
"Provision a development environment at 10.92.3.50"
"What's the next available CTID for utility containers?"

Natural Language Examples:

• "I need a new container for Plex with 8GB RAM and SSL enabled"

• "Create a monitoring stack at 10.92.3.60 with Grafana access"

• "Deploy a dev environment with 2 cores and 32GB disk"

Direct API Usage

# Start the server
npm start

# The server communicates via stdio using MCP protocol

🔐 Security

API Token Setup (Recommended)

1. Log into Proxmox web interface

2. Go to Datacenter → Permissions → API Tokens

3. Create a new token with appropriate permissions

4. Use the token in your configuration

Required Permissions

• VM.Audit - View VM information

• VM.PowerMgmt - Start/stop VMs

• Sys.Audit - View node information

• Datastore.Audit - View storage information

🧪 Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• Model Context Protocol

• MCP TypeScript SDK

• Proxmox VE API Documentation

📞 Support

• 🐛 Report Issues

• 💬 Discussions

• 📧 Contact