PVE

English | 繁體中文 | 简体中文

$ pve_add_dns { "host": "dnscheck.internal", "ip": "10.10.10.250", "yes": true }
{"host": "dnscheck.internal", "ip": "10.10.10.250", "action": "added", "verified": true}

A single-node Proxmox lab with a gateway runs on many small chores: guests, port forwards, internal DNS records and reverse-proxy sites. This plugin gives Codex and Claude Code 16 tools for them over SSH. Each tool that changes something needs an explicit confirmation.

Features

• Manages guests: lists, inspects, starts, stops, clones and destroys VMs and containers. A destroy also removes the guest's forwards, DNS records, Caddy sites and SSH alias.

• Forwards ports: adds and removes iptables DNAT rules on the host and keeps them across reboots.

• Edits internal DNS: adds and removes *.internal records in the gateway's dnsmasq, then verifies each change with dnsmasq.

• Edits Caddy sites: previews the diff, runs caddy validate, reloads Caddy and rolls back when the reload fails.

Related MCP server: Proxmox MCP Server

Quick start

claude plugin marketplace add zyx1121/marketplace
claude plugin install pve@zyx1121

Codex: codex plugin marketplace add zyx1121/marketplace, then codex plugin add pve@zyx1121.

Copy examples/pve.config.example.json to ~/.config/pve/config.json (mode 600), and set your host aliases, gateway paths and template IDs. Start a new session and ask "List my VMs".

The plugin needs Bun 1.3.13 or later, uv, SSH, and Python 3.11 or later. The MCP server ships bundled.

Usage

• Tools that change something need yes or confirm. pve_stop_guest cuts the power, and pve_destroy_guest cannot be undone.

• The DNS tools manage the internal dnsmasq only, not public DNS.

• A call has a 120-second limit. A timeout does not mean a rollback, so look at the remote state before you retry.

Configuration

~/.config/pve/config.json holds the profile. PVE_CONFIG_PATH and XDG_CONFIG_HOME move it.

Each key also reads PVE_<KEY>, which wins over the older UTILS_PVE_<KEY>, which wins over the file. SSH config keeps the users and keys. Secrets stay on the gateway. Without a profile, the tools return a setup error instead of guessing a network.

How it works

The Bun MCP server runs each call as a Python script under uv. The script works over SSH on the host or the gateway.

• DNS edits fail before they write when dnsmasq does not read the configured hosts file. After a reload, the tools ask dnsmasq with dig and report verified.

• The tools write the hosts file in place, so a symlinked file stays a symlink.

• Port forwards persist to /etc/iptables/rules.v4 without the rules that the SDN adds by itself.

Limits

• One Proxmox node with an IPv4 /24 guest network, and the VMID, SSH port and firewall group conventions of this lab. It is not a general cluster manager.

• The template, bridge, firewall group and gateway services in the profile must exist first.

For AI agents

Facts for coding agents and LLM tools. The rules for changing the code are in AGENTS.md.

• Summary: Plugin with 16 MCP tools for a single-node Proxmox host and its gateway: guests, forwards, dnsmasq records and Caddy sites.

• Type: plugin

• Interfaces: MCP pve (stdio, dist/server.js). scripts/pve.py also runs as a CLI under uv.

• Install: claude plugin install pve@zyx1121, after claude plugin marketplace add zyx1121/marketplace

• Run: the host starts the MCP server

• Verify: call pve_list_guests, or pve_list_dns and expect served: true

• Config: ~/.config/pve/config.json, PVE_CONFIG_PATH, and PVE_<KEY> for each profile key

• Secrets: none in the plugin. SSH keys stay in SSH config, and gateway secrets stay on the gateway.

• Limits: one node and one /24 guest network. Stop and destroy act at once after confirmation.

Development

bun install --frozen-lockfile
bun run check

The tests use a fake SSH and temporary files, so they never touch a real host. plugin.json and mcp.json are the manifest sources. CI fails when the generated files are stale.

License

MIT