ProxmoxEmCP

Proxmox MCP Server


     

A Model Context Protocol (MCP) server for managing Proxmox VE infrastructure through AI assistants. Available as an npm package, Docker container, or standalone Python application.

Project Background

In May 2025, we launched the original ProxmoxMCP server with FastMCP, FastAPI, and virtual environments. Based on community feedback and operational experience, we rebuilt the project as ProxmoxEmCP - a cleaner, simpler implementation that eliminates setup complexity while maintaining full functionality. This version uses the official MCP SDK directly and runs without virtual environment dependencies, making deployment and maintenance significantly easier.

Table of Contents

• Quick Start
• npm/npx
• Docker Hub
• Prerequisites
• Installation Methods
• npm Package
• Docker Container
• Local Python
• Open WebUI Integration
• Configuration
• Environment Variables
• Creating API Token
• AI Agent Integration
• Available MCP Tools
• Node Management
• VM Operations
• Container Operations
• Storage & Backup
• Monitoring & Logs
• Access Control
• Network & Security
• Architecture
• Development
• Troubleshooting
• License
• Support

Quick Start

npm/npx

# Install globally
npm install -g @puregrain/proxmox-emcp-node

# Or run directly with npx
npx @puregrain/proxmox-emcp-node

Docker Hub

docker run -d \
  --name proxmox-emcp \
  -e PROXMOX_HOST="192.168.1.100" \
  -e PROXMOX_TOKEN_ID="your-token-id" \
  -e PROXMOX_TOKEN_SECRET="your-token-secret" \
  puregrain/proxmox-emcp:latest

Prerequisites

• Proxmox VE: Version 7.0 or higher with API access enabled
• For npm package: Node.js 18+
• For Docker: Docker Engine installed
• For local Python: Python 3.9+
• API Token: Created in Proxmox with appropriate permissions

Installation Methods

npm Package

The npm package provides a native Node.js implementation without Docker requirements.

# Install globally
npm install -g @puregrain/proxmox-emcp-node

# Set environment variables
export PROXMOX_HOST="192.168.1.100"
export PROXMOX_TOKEN_ID="your-token-id"
export PROXMOX_TOKEN_SECRET="your-token-secret"

# Run the server
proxmox-emcp-node

Using with npx (no installation required):

PROXMOX_HOST=192.168.1.100 \
PROXMOX_TOKEN_ID=your-token-id \
PROXMOX_TOKEN_SECRET=your-token-secret \
npx @puregrain/proxmox-emcp-node

Docker Container

Using Docker Compose (Recommended)

1. Clone the repository:

git clone https://github.com/PureGrain/ProxmoxEmCP.git
cd ProxmoxEmCP

1. Configure environment:

cp .env.example .env
# Edit .env with your Proxmox credentials

1. Start the container:

docker-compose up -d

Using Docker CLI

docker run -d \
  --name proxmox-emcp \
  -e PROXMOX_HOST="192.168.1.100" \
  -e PROXMOX_TOKEN_ID="your-token-id" \
  -e PROXMOX_TOKEN_SECRET="your-token-secret" \
  puregrain/proxmox-emcp:latest

Using GitHub Container Registry

docker run -d \
  --name proxmox-emcp \
  -e PROXMOX_HOST="192.168.1.100" \
  -e PROXMOX_TOKEN_ID="your-token-id" \
  -e PROXMOX_TOKEN_SECRET="your-token-secret" \
  ghcr.io/puregrain/proxmox-emcp:latest

Local Python

# Clone the repository
git clone https://github.com/PureGrain/ProxmoxEmCP.git
cd ProxmoxEmCP

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export PROXMOX_HOST="192.168.1.100"
export PROXMOX_TOKEN_ID="your-token-id"
export PROXMOX_TOKEN_SECRET="your-token-secret"

# Run the server
python mcp_server_stdio.py

Open WebUI Integration

For Open WebUI users, we provide ProxmoxWeaver - a specialized tool that brings full Proxmox management capabilities directly into your Open WebUI interface.

ProxmoxWeaver is a native Open WebUI tool that provides the same comprehensive Proxmox VE management features as our MCP server, but specifically designed for the Open WebUI ecosystem.

Features:

• Direct integration with Open WebUI's tool system
• Same powerful Proxmox management capabilities
• No additional containers or services required
• Simple installation through Open WebUI's tool marketplace

Installation:

1. Visit the ProxmoxWeaver repository
2. Copy the tool configuration
3. In Open WebUI, navigate to Tools → Add Tool
4. Paste the ProxmoxWeaver configuration
5. Configure your Proxmox credentials in the tool settings

Usage:

Once installed, ProxmoxWeaver appears as a native tool in Open WebUI, allowing you to:

• Query and manage VMs and containers
• Monitor cluster health and resources
• Execute commands and create snapshots
• Manage storage, backups, and templates
• All through natural language interactions in Open WebUI

This integration is perfect for teams already using Open WebUI who want to add Proxmox management capabilities without additional infrastructure.

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PROXMOX_HOST | Yes | - | Proxmox server IP or hostname | | PROXMOX_TOKEN_ID | Yes | - | API token ID | | PROXMOX_TOKEN_SECRET | Yes | - | API token secret | | PROXMOX_USER | No | root@pam | Proxmox user | | PROXMOX_VERIFY_SSL | No | false | Verify SSL certificates | | LOG_LEVEL | No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |

Creating API Token

1. Log into Proxmox Web UI
2. Navigate to Datacenter → Permissions → API Tokens
3. Click Add to create a new token
4. Configure the token:

• User: Select your user (e.g., root@pam)
• Token ID: Choose a descriptive name
• Privilege Separation: Uncheck for full user permissions

1. Copy the token secret (shown only once!)

AI Agent Integration

Configure your AI assistant (Claude Desktop, Cline, or any MCP-compatible client) to connect to the server.

For npm Package

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": ["@puregrain/proxmox-emcp-node"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_ID": "your-token-id",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

For Docker Container

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["attach", "proxmox-emcp"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_ID": "your-token-id",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Available MCP Tools

Node Management

• get_nodes - List all nodes in the cluster
• get_node_status - Get detailed status for a specific node

VM Operations

• get_vms - List all VMs across the cluster
• get_vm_status - Get VM status and configuration
• start_vm - Start a virtual machine
• stop_vm - Stop a virtual machine gracefully
• reboot_vm - Reboot a virtual machine
• execute_vm_command - Execute commands via QEMU guest agent
• create_vm_snapshot - Create a VM snapshot
• list_vm_snapshots - List all snapshots for a VM
• get_vm_network - Get VM network configuration

Container Operations (LXC)

• get_containers - List all LXC containers
• get_container_status - Get container status and configuration
• start_container - Start a container
• stop_container - Stop a container gracefully
• reboot_container - Reboot a container
• execute_container_command - Execute commands in container
• create_container_snapshot - Create a container snapshot
• list_container_snapshots - List container snapshots

Storage & Backup

• get_storage - List storage pools
• get_storage_details - Get detailed storage pool information
• get_backups - List backup files with filtering
• list_templates - List VM and container templates

Monitoring & Logs

• get_cluster_status - Get comprehensive cluster health and resources
• get_task_status - Check Proxmox task status
• get_recent_tasks - List recent tasks with filtering
• get_cluster_log - Get cluster-wide log entries

Access Control

• get_users - List all users with groups and tokens
• get_groups - List all groups with members
• get_roles - List all roles and privileges

Network & Security

• get_firewall_status - Get firewall status and rules

Architecture

┌─────────────────┐
│   AI Assistant  │
│  (Claude, etc)  │
└────────┬────────┘
         │ MCP Protocol
         ▼
┌─────────────────┐
│   MCP Server    │
│  (Node/Python)  │
└────────┬────────┘
         │ REST API
         ▼
┌─────────────────┐
│  Proxmox VE     │
│    Cluster      │
└─────────────────┘

Development

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm test or python -m pytest
5. Submit a pull request

Pre-commit Hooks

This project uses pre-commit for code quality:

pip install pre-commit
pre-commit install
pre-commit run --all-files

Hooks include:

• black - Python code formatter
• flake8 - Python linter
• detect-secrets - Secret scanning
• YAML and whitespace validation

Building Docker Image

docker build -t proxmox-emcp .

Modifying the Server

• Node.js version: Edit files in npm-app/
• Python version: Edit mcp_server_stdio.py
• Docker config: Edit Dockerfile and docker-compose.yml

Troubleshooting

Connection Issues

• Verify Proxmox is reachable: ping <PROXMOX_HOST>
• Check API port: Ensure port 8006 is accessible
• SSL certificates: Set PROXMOX_VERIFY_SSL=false for self-signed certs

Authentication Failures

• Token permissions: Ensure token has required permissions
• Token format: Verify TOKEN_ID and TOKEN_SECRET are correct
• User privileges: Check user has appropriate Proxmox permissions

Viewing Logs

# Docker logs
docker logs proxmox-emcp

# npm/Node.js - set LOG_LEVEL
LOG_LEVEL=DEBUG npx @puregrain/proxmox-emcp-node

Common Issues

• "Connection refused": Check firewall and Proxmox API service
• "Unauthorized": Verify token credentials
• "SSL verification failed": Set PROXMOX_VERIFY_SSL=false

License

This project is dual-licensed under the following terms:

• MIT License: For open-source use. See the LICENSE file for details.
• Commercial License: For proprietary use. See the COMMERCIAL-LICENSE.txt file for details.

For commercial licensing inquiries, please contact: [Your Email or Website]

Support

• Issues: GitHub Issues
• Documentation: MCP Configuration Guide
• Sponsor: GitHub Sponsors

---

Author: PureGrain at SLA Ops, LLC Repository: github.com/PureGrain/ProxmoxEmCP