# proxmox-mcp

A **read-only** Model Context Protocol server for Proxmox VE. It gives an AI assistant accurate,
structured visibility into your cluster and the Docker workloads inside your guests — and it
cannot change anything, by construction rather than by convention.

Works with any Proxmox cluster: single-node or multi-node, LXC or QEMU or both, any addressing
scheme, any SSH username, any storage backend.

## Why read-only is structural here

Several Proxmox MCP servers exist. Most expose `stop_guest`, `delete_guest`, or `exec_command`
alongside their read tools. This one cannot, and the difference is not a promise in a README:

- **No mutating tool is registered, and no code path for one exists.**
- **Every command is matched against an allowlist before a connection is opened.** 18 permitted
  forms, exact-match on the whole argument vector. Anything else is refused and audited.
- **There is no generic shell.** No tool accepts an arbitrary command string. `docker --format`
  values are pinned literals, because a Go template is an expression language — `--format
  '{{.Config.Env}}'` would print your container secrets.
- **Container environment variables are never returned.** The `docker inspect` template projects
  only the fields the tools consume, so environment is never serialised on the far side at all.
- **Your credentials never reach the model.** A tool call passes at most a *profile name*. Hosts,
  users, and key paths are resolved server-side.
- **Every call is audited**, including refusals, with no argument value that could carry a secret.

The allowlist and its 18 refusal classes live in `src/proxmoxmcp/transport/allowlist.py`
as declarative data, so they can be audited by reading rather than by tracing code. An independent
adversarial pass — roughly 160 hostile inputs over stdio against the installed artifact: command
separators, traversal, flag smuggling, unicode digits, poisoned configuration, concurrency, process
kills — found no escape and no route to a mutating command.

## Requirements

- Python **3.11+**
- [`uv`](https://docs.astral.sh/uv/)
- SSH access from the machine running the server to each Proxmox node, key-based and
  non-interactive. The server never manages keys and never prompts.

## Install

`uv` is the supported path. Not yet on PyPI, so install from the repository.

A note on names, since they differ on purpose: the command you run is **`proxmox-mcp`** and the
MCP server registers as **`proxmox-mcp`**. The Python distribution is **`proxmoxmcp`**, because
`proxmox-mcp`, `mcp-proxmox`, `proxmox-mcp-server` and `pve-mcp` are all already taken on PyPI —
by packages that install a top-level `proxmox_mcp` and therefore cannot coexist with each other.
You only ever type `proxmoxmcp` when installing from a local path.

```bash
uv tool install git+https://github.com/edymol/proxmox-mcp
```

Or from a local clone:

```bash
git clone https://github.com/edymol/proxmox-mcp
cd proxmox-mcp
uv tool install --from . proxmoxmcp
```

Pin the interpreter if you want the declared minimum rather than whatever `uv` picks:

```bash
uv tool install --python 3.11 --from . proxmoxmcp
```

Find the installed executable — you need its absolute path to register it:

```bash
echo "$(uv tool dir --bin)/proxmox-mcp"
```

To try it without installing, `uvx --from . proxmoxmcp` runs it from a temporary
environment.

## Configure

Create `~/.config/proxmox-mcp/profiles.toml`, or set `$PROXMOX_MCP_HOME` and put
it there. An annotated example ships in the package at `resources/profiles.example.toml`.

```toml
[profiles.homelab]
nodes              = ["node-a", "node-b"]   # SSH destinations; one entry is fine
ssh_user           = "root"                 # optional, defers to your ssh_config
ssh_config         = "~/.ssh/config"        # optional, defers to the SSH default
permitted_networks = ["10.0.0.0/24"]        # optional, only check_ip_availability needs it
```

Nothing is guessed. Absent configuration produces an error naming the missing setting rather than a
default. Verify SSH access first — `BatchMode` turns an unknown host key into a failure:

```bash
ssh -o BatchMode=yes node-a true
```

## Register with an MCP client

The server speaks Model Context Protocol over stdio. Every MCP client provides its own
configuration mechanism. Consult your client's documentation for the configuration file location
and format.

Find the installed executable first:

```bash
echo "$(uv tool dir --bin)/proxmox-mcp"
```

Then register it by absolute path. The generic MCP stdio block below works with any client that
accepts standard `mcpServers` configuration:

```json
{
  "mcpServers": {
    "proxmox-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/proxmox-mcp",
      "args": [],
      "env": {}
    }
  }
}
```

For TOML-based configuration:

```toml
[mcp_servers.proxmox-mcp]
command = "/absolute/path/to/proxmox-mcp"
args = []
```

Two operationally important notes:

1. **Configuration is read at process start.** If you edit your client's configuration file,
   restart the client process. A refresh or reconnect inside a running session is not sufficient.

2. **Some clients require per-tool approval.** If your client is configured with a policy of never
   approving MCP tool calls automatically, you must explicitly approve each tool before it can be
   called. Without this configuration, every tool call is cancelled and reported as user
   cancellation, which reads like a server fault and is not one. Consult your client's
   documentation for the approval mechanism.

## The twelve tools

| Tool | Returns |
|---|---|
| `list_nodes` | Every node: online state, cores, memory, root filesystem, uptime, PVE version |
| `get_node_capacity` | One node in detail: CPU, memory, swap, per-mount filesystems, headroom |
| `list_guests` | Every LXC and VM, running and stopped, with node, resources, pool, tags |
| `get_guest_config` | Cores, memory, disks, network interfaces with bridge and gateway, features |
| `get_guest_status` | Live state, uptime, CPU, memory, disk and network counters, HA state |
| `list_storage` | Storage entries with type, content, totals, and a per-node breakdown |
| `list_snapshots` | Snapshots for one guest with parent, description, timestamp, RAM flag |
| `list_backups` | Backup volumes with guest, format, size, timestamp, newest age per guest |
| `check_ip_availability` | Whether an address is in use, with the evidence for the answer |
| `list_guest_containers` | Docker containers in an LXC: image, state, health, ports, compose labels |
| `inspect_compose_stack` | One compose project: services, images, states, networks, mount paths |
| `guest_health_summary` | One consolidated read with concrete concerns — **start here** |

Ask "how is guest 101 doing" and a model should reach for `guest_health_summary` first.

Two behaviours worth knowing. `check_ip_availability` reports `free` **only** when every check ran
and every check agreed — a partial answer may say `in_use` but never `free`, because a wrong `free`
means a duplicate address on a live network. And `list_storage` reports `available` as null where no
source measures it, rather than deriving `total - used`, which overstates real free space.

## Development

```bash
uv sync
uv run ruff check
```

**The test suite is not published here.** It is maintained privately: 1225 tests across unit
(against a fake transport, no network), integration (recorded cluster fixtures), installed
(a UV-installed artifact outside the checkout), and portability layers, plus opt-in read-only
live tests.

Stating the obvious consequence rather than glossing it: **you cannot verify the claims in the
section above from this repository alone.** You can read `transport/allowlist.py`, which is
declarative data and is the whole enforcement surface, and you can read every tool in `tools/` and
confirm none of them performs I/O. Those two readings are what the tests check. If you want the
suite before pointing this at a hypervisor, ask.

## Status, and what is not finished

v1 is read-only. Mutating tools (`start_guest`, `create_lxc`, and so on) are designed but
deliberately not built: they need dry-run plans, confirmation tokens, and pre-destruction checks
that do not exist yet.

Known limits, recorded rather than hidden:

- `list_snapshots` and `list_backups` presence paths were developed against synthetic fixtures. The
  cluster this was built against has no snapshots and no backups, so first contact with real ones
  deserves a careful look.
- Discovery contacts each configured node in turn with a 10-second connect timeout, and profiles are
  capped at 256 nodes. A profile full of unreachable-but-routable hosts is therefore slow; a
  wall-clock deadline on discovery is the real fix and is not written yet.
- Known open items are tracked outside this repository, not because they are hidden but because the
  ledgers are part of a private build process. The material ones are listed above.

## Licence

MIT. See [LICENSE](LICENSE).