Proxmox VE 集群管理 MCP 服务

proxmox-mcp

An MCP server that exposes Proxmox VE cluster operations as tools, built in Go using the official go-sdk. Tool responses are compact JSON (no indentation) to minimise token usage.

Tools

Cluster & Nodes

QEMU VMs

LXC Containers

Backups

Tasks

Network

Firewall

Pool Management

Storage Content

Storage Definitions

Access Control

Destructive (opt-in)

These tools are not registered by default. Set PROXMOX_ALLOW_DESTRUCTIVE=true to enable them.

Lifecycle and snapshot operations are non-blocking — they return the UPID of the async task immediately. Use get_task_status to poll for completion.

Installation

Download a pre-built binary

Download the latest release for your platform from the Releases page.

Each release also includes checksums.txt with SHA-256 hashes of every binary. Download it into the same directory and verify before running:

# Linux
sha256sum --check --ignore-missing checksums.txt
# macOS
shasum -a 256 --check --ignore-missing checksums.txt

Windows users can compare the output of Get-FileHash proxmox-mcp_windows_amd64.exe (PowerShell) against the matching line.

Make it executable and place it on your PATH (substitute the filename for your platform):

chmod +x <binary-name>
mv <binary-name> /usr/local/bin/proxmox-mcp

Windows users: rename the .exe and add it to a directory on your %PATH%.

macOS users: if Gatekeeper blocks the downloaded binary, clear the quarantine flag with xattr -d com.apple.quarantine /usr/local/bin/proxmox-mcp.

Install with Go

Requires Go 1.27.3+. Installs proxmox-mcp into $(go env GOPATH)/bin:

go install github.com/gordcurrie/proxmox-mcp/cmd/proxmox-mcp@latest

Build from source

Requires Go 1.27.3+. You will also need a Proxmox VE API token — create one in Datacenter → Permissions → API Tokens.

git clone https://github.com/gordcurrie/proxmox-mcp
cd proxmox-mcp
cp .env.example .env   # copy the example env file
$EDITOR .env           # set PROXMOX_* values (see table below)
make build             # binary lands in bin/proxmox-mcp

Configuration

All configuration is via environment variables:

Source your .env file before running:

set -a && source .env && set +a

Running

stdio (default — for local MCP clients)

./bin/proxmox-mcp

HTTP (streamable — for remote/shared deployments)

./bin/proxmox-mcp --transport http --addr localhost:8080

Claude Code configuration

claude mcp add proxmox --scope user \
  -e PROXMOX_API_URL=https://your-proxmox-host:8006/api2/json \
  -e 'PROXMOX_TOKEN_ID=user@realm!tokenid' \
  -e PROXMOX_TOKEN_SECRET=your-token-secret \
  -- /path/to/proxmox-mcp

If your Proxmox host uses its default self-signed certificate, add -e PROXMOX_INSECURE=true. This disables TLS certificate and hostname verification, so only use it on a trusted network.

Run /mcp inside Claude Code to confirm the server is connected. Install the agent skills too, so Claude knows when and how to use the tools.

VS Code Copilot configuration

Create .vscode/mcp.json in your workspace (already gitignored):

{
  "servers": {
    "proxmox-mcp": {
      "type": "stdio",
      "command": "/path/to/proxmox-mcp/bin/proxmox-mcp",
      "env": {
        "PROXMOX_API_URL": "https://your-proxmox-host:8006/api2/json",
        "PROXMOX_TOKEN_ID": "user@realm!tokenid",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Then open the Copilot chat panel, switch to Agent mode, and the proxmox-mcp server will appear in the available tools.

Claude Desktop configuration

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "/path/to/proxmox-mcp/bin/proxmox-mcp",
      "env": {
        "PROXMOX_API_URL": "https://your-proxmox-host:8006/api2/json",
        "PROXMOX_TOKEN_ID": "user@realm!tokenid",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Restart Claude Desktop after saving the config — the Proxmox tools will appear in the tool selector.

OpenCode configuration

Add the server to opencode.json in your project root (or ~/.config/opencode/opencode.json for global config):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "proxmox-mcp": {
      "type": "local",
      "command": ["/path/to/proxmox-mcp/bin/proxmox-mcp"],
      "enabled": true,
      "environment": {
        "PROXMOX_API_URL": "https://your-proxmox-host:8006/api2/json",
        "PROXMOX_TOKEN_ID": "user@realm!tokenid",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Agent skills

The skills/ directory contains Agent Skills (SKILL.md format) that teach an agent how to use these tools well:

Inside this repo they are already available to Claude Code and Copilot via .claude/skills and .github/skills, which link to skills/.

To use them in all your projects with Claude Code, symlink each skill into your user skills directory, so a git pull keeps them current:

git clone https://github.com/gordcurrie/proxmox-mcp
mkdir -p ~/.claude/skills
for s in "$PWD"/proxmox-mcp/skills/*/; do ln -s "${s%/}" ~/.claude/skills/; done

If you install them globally, Claude Code sees each skill twice while you work inside this repo (once from ~/.claude/skills, once from .claude/skills); both point at the same files, so they never disagree. Other agents that support Agent Skills (GitHub Copilot, Cursor, Codex CLI, Gemini CLI, …) read the same folder layout; link or copy the skills into that agent's skills directory.

On Windows, clone with symlinks enabled (git clone -c core.symlinks=true …, which needs Developer Mode or admin rights); otherwise .claude/skills and .github/skills are checked out as plain text files and the in-repo skills do not load. Copy skills/* into your agent's skills directory instead.

Development

make install-tools   # install golangci-lint, gosec, govulncheck, gofumpt
make check           # full quality gate: fix, fmt, vet, lint, sec, vulncheck, test, build
make test            # tests only (with race detector)
make build           # build only → bin/proxmox-mcp
make clean           # remove bin/proxmox-mcp