Proxmox SSH MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to execute commands on a Proxmox host via SSH.

Features

SSH key-based authentication (no passwords in code)
Built-in security: dangerous commands are blocked
Single tool: proxmox_run_host_command

Prerequisites

Node.js 18+
SSH key pair (~/.ssh/id_ed25519)
Public key added to Proxmox server's ~/.ssh/authorized_keys

Installation

git clone https://github.com/Zaptimist/mcp-proxmox.git
cd mcp-proxmox
npm install

Configuration

Set your Proxmox host via environment variables or edit index.js:

Option 1: Environment variables (recommended)

export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root
export PROXMOX_PORT=22
export PROXMOX_KEY_PATH=~/.ssh/id_ed25519

Option 2: Edit index.js directly

const sshConfig = {
  host: process.env.PROXMOX_HOST || '192.168.1.100',  // Your Proxmox IP
  username: process.env.PROXMOX_USER || 'root',
  port: parseInt(process.env.PROXMOX_PORT) || 22,
  privateKeyPath: process.env.PROXMOX_KEY_PATH || path.join(os.homedir(), '.ssh', 'id_ed25519')
};

SSH Key Setup

The MCP server will automatically detect if SSH keys are missing or not configured and provide setup instructions. But here's the manual process:

Generate a key (if you don't have one):
```
ssh-keygen -t ed25519
```

Copy public key to Proxmox:

Windows (PowerShell):

type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh root@YOUR_PROXMOX_IP "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

Linux/Mac:

ssh-copy-id root@YOUR_PROXMOX_IP

Test the connection:

ssh root@YOUR_PROXMOX_IP "echo 'SSH key auth works!'"

If you haven't set up SSH keys yet, the MCP server will return helpful instructions when you try to use it.

MCP Client Configuration

Add to your MCP client config (e.g., ~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/path/to/mcp-proxmox/index.js"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100"
      },
      "disabled": false,
      "autoApprove": ["proxmox_run_host_command"]
    }
  }
}

Usage

The server exposes one tool:

`proxmox_run_host_command`

Execute a command on the Proxmox host.

Input:

command (string, required): The command to execute

Example:

{
  "command": "qm list"
}

Response:

{
  "success": true,
  "command": "qm list",
  "host": "192.168.1.100",
  "exitCode": 0,
  "stdout": "VMID NAME STATUS MEM(MB) ...",
  "stderr": ""
}

Security

The following commands are blocked for safety:

VM/Container deletion (qm destroy, pct destroy)
File operations (rm, rmdir, dd)
System operations (shutdown, reboot, halt)
Package removal (apt remove, apt purge)
Service management (systemctl stop)
Storage deletion (zfs destroy, lvremove)

Destructive actions must be performed manually via the Proxmox web interface.

License

MIT