Proxmox MCP Server

A Model Context Protocol (MCP) server for managing Proxmox Virtual Environment servers.

Overview

This MCP server provides tools for interacting with Proxmox VE through the Model Context Protocol, allowing AI agents and other MCP clients to manage virtual machines, containers, and system resources.

Installation

npm install @example/proxmox-mcp-server

Or run directly with npx:

npx @example/proxmox-mcp-server

Deployment Options

The Proxmox MCP server can be deployed in multiple ways:

1. Direct execution with npx (as shown above)
2. Docker container using the provided Dockerfile
3. LXC container on Proxmox hosts
4. Installation from npm for global access

See Deployment Options for detailed instructions on each method.

Configuration

The server can be configured through environment variables using either API tokens or username/password authentication:

API Token Authentication (Recommended)

Variable	Description	Default
PROXMOX_HOST	Proxmox server hostname or IP	192.168.254.10
PROXMOX_PORT	Proxmox API port	8006
PROXMOX_API_TOKEN	Proxmox API token	(required)
PROXMOX_USER	Proxmox user for API token	root@pam

Username/Password Authentication

Variable	Description	Default
PROXMOX_HOST	Proxmox server hostname or IP	192.168.254.10
PROXMOX_PORT	Proxmox API port	8006
PROXMOX_USER	Proxmox username	root@pam
PROXMOX_PASSWORD	Proxmox password	(required)

Note: If both PROXMOX_API_TOKEN and PROXMOX_PASSWORD are provided, API token authentication takes precedence.

For detailed instructions on using username/password authentication, see USING-USERNAME-PASSWORD-AUTH.md.

Tools Provided

Read-Only Tools (Generally Available)

1. list_vms - List all virtual machines
2. list_containers - List all containers
3. get_vm_status - Get status of a specific VM
4. get_system_info - Get system information
5. get_storage_info - Get storage information
6. get_cluster_status - Get overall cluster status
7. get_node_status - Get detailed status of a specific node
8. list_vm_snapshots - List snapshots for a VM
9. list_backups - List available backups
10. get_performance_metrics - Get performance metrics

Modify Tools (Require Modify Permissions)

1. start_vm - Start a specific VM
2. stop_vm - Stop a specific VM
3. create_vm_snapshot - Create a snapshot of a VM
4. rollback_vm_snapshot - Rollback a VM to a specific snapshot

Create Tools (Require Create Permissions)

1. clone_vm - Clone an existing VM

Delete Tools (Require Delete Permissions)

1. delete_vm_snapshot - Delete a specific snapshot

Backup Tools (Require Backup Permissions)

1. create_backup - Create a backup of a VM/container

Permission-Based Tool Availability

The server implements permission-based tool availability based on the permissions of the provided API token or user account:

• Tools are registered dynamically based on the permissions of the provided credentials
• Read-only tools are generally available to all users
• Modification tools require appropriate permissions
• Creation, deletion, and backup tools require specific permissions

Usage

With API Token Authentication (Recommended)

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": [
        "-y",
        "@example/proxmox-mcp-server"
      ],
      "env": {
        "PROXMOX_HOST": "192.168.254.10",
        "PROXMOX_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

With Username/Password Authentication

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": [
        "-y",
        "@example/proxmox-mcp-server"
      ],
      "env": {
        "PROXMOX_HOST": "192.168.254.10",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_PASSWORD": "your-password-here"
      }
    }
  }
}

Direct Usage

With API Token:

PROXMOX_HOST=192.168.254.10 PROXMOX_API_TOKEN=your-token npx @example/proxmox-mcp-server

With Username/Password:

PROXMOX_HOST=192.168.254.10 PROXMOX_USER=root@pam PROXMOX_PASSWORD=your-password npx @example/proxmox-mcp-server

Development

1. Clone the repository
2. Install dependencies: npm install
3. Run in development mode: npm run dev

LXC Container Deployment

The Proxmox MCP server can also be deployed as an LXC container on your Proxmox host for better isolation and management.

Prerequisites

1. Proxmox VE host with LXC support
2. Internet connectivity for package installation

Deployment

1. Navigate to the LXC deployment directory:

   cd ../proxmox-mcp-lxc

2. Review and modify the setup script if needed:

   nano setup.sh

3. Run the setup script:

   chmod +x setup.sh
   ./setup.sh

4. Configure authentication by editing the environment file:

   pct exec 200 -- nano /etc/proxmox-mcp-server.env

5. Start the service:

   pct exec 200 -- rc-service proxmox-mcp-server start

For detailed instructions, see the LXC README.

Security

API Token Authentication (Recommended)

• More secure as tokens can be restricted to specific permissions
• Tokens can be easily revoked without changing user passwords
• Tokens can have expiration dates

Username/Password Authentication

• Less secure as it requires storing passwords
• Password compromise affects all systems using that password

For detailed security considerations and best practices for username/password authentication, see USING-USERNAME-PASSWORD-AUTH.md.