# proxmox-mcp

**Give Claude (and any other LLM agent) hands on your Proxmox VE cluster.** A small, dependency-light [Model Context Protocol](https://modelcontextprotocol.io) server that turns cluster status, VM/container lifecycle, and node control into first-class tools.

[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-6E56CF)](https://modelcontextprotocol.io)

Ask *"is anything down in my cluster?"* and get a real answer. Say *"restart the pihole container"* and it happens — with a task UPID you can follow to completion. No SSH gymnastics, no hand-crafted API tokens in your shell history.

## What it does

The server exposes eight tools over MCP, split into read and write:

**Read**

- **`proxmox_status`** — Full cluster snapshot: nodes (CPU/RAM), running vs. stopped VMs and containers, and storage pools with a warning at ≥85% usage.
- **`proxmox_find`** — Locate a VM or container by name (partial match) and get its `vmid`, node, and type — the details you need before acting on it.
- **`proxmox_task_status`** — Follow a running or finished Proxmox task by its UPID, including the last log lines and exit status.

**Write**

- **`proxmox_vm_action`** — Lifecycle control for a VM: `start`, `stop`, `shutdown`, `reset`, `suspend`, `resume`.
- **`proxmox_container_action`** — Lifecycle control for an LXC container: `start`, `stop`, `shutdown`, `reboot`, `suspend`, `resume`.
- **`proxmox_node_action`** — `reboot` or `shutdown` a node.
- **`proxmox_delete_vm`** — Permanently delete a stopped VM.
- **`proxmox_delete_container`** — Permanently delete a stopped container.

Every write returns a task UPID so the agent can verify the outcome with `proxmox_task_status`.

## Install

The console script `proxmox-mcp` starts the server over stdio.

**pipx** (isolated, recommended for a global install)

```bash
pipx install git+https://github.com/ManciDRaffy/proxmox-mcp.git
```

**uv**

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

**pip, from source**

```bash
git clone https://github.com/ManciDRaffy/proxmox-mcp.git
cd proxmox-mcp
pip install .
```

## Configure

All configuration comes from environment variables — there are no host-specific defaults baked into the code. Copy `.env.example` to `.env`, or export them directly.

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `PROXMOX_API_URL` | Yes | — | Base URL of the Proxmox VE API, including the port, e.g. `https://proxmox.example.com:8006`. |
| `PROXMOX_TOKEN` | Yes | — | API token in the form `user@realm!tokenid=uuid`. |
| `PROXMOX_VERIFY_SSL` | No | `true` | Set to `false` to skip TLS verification (self-signed certs). Any other value keeps it on. |
| `PROXMOX_CLUSTER_CACHE_SECONDS` | No | `30` | TTL for cached cluster snapshots. `0` disables caching. |

**Creating a token:** in the Proxmox web UI go to *Datacenter → Permissions → API Tokens*, add a token for a user, and give that user the roles it needs (`PVEAuditor` for read-only; add `PVEVMAdmin` for lifecycle actions). The token string has the exact shape `user@realm!tokenid=uuid` — for example `root@pam!mcp=00000000-0000-0000-0000-000000000000`.

## Use with Claude Desktop

Add the server to your `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "proxmox": {
      "command": "proxmox-mcp",
      "env": {
        "PROXMOX_API_URL": "https://proxmox.example.com:8006",
        "PROXMOX_TOKEN": "root@pam!mcp=00000000-0000-0000-0000-000000000000",
        "PROXMOX_VERIFY_SSL": "true",
        "PROXMOX_CLUSTER_CACHE_SECONDS": "30"
      }
    }
  }
}
```

Restart Claude Desktop and the eight `proxmox_*` tools appear. If `proxmox-mcp` is not on Claude's `PATH`, use its absolute path (find it with `which proxmox-mcp`) or run it via your tool manager, e.g. `"command": "uv", "args": ["tool", "run", "proxmox-mcp"]`.

## Security

- **Read vs. write.** Three tools are strictly read-only (`proxmox_status`, `proxmox_find`, `proxmox_task_status`). The rest change cluster state, and two of them (`proxmox_delete_vm`, `proxmox_delete_container`) are **destructive and irreversible**. Scope your API token to exactly what you want the agent to do — a `PVEAuditor`-only token makes the whole server safely read-only.
- **`PROXMOX_VERIFY_SSL`.** TLS verification is **on by default**. Only set it to `false` for clusters using self-signed certificates, and prefer installing your CA over disabling verification.
- **Credentials.** The token is read from the environment and never logged. Keep your `.env` out of version control (it is already in `.gitignore`) and never commit real tokens.
- **Least privilege.** Give the token's user only the roles required for the actions you intend to allow, and remember that lifecycle and delete actions run with whatever permissions that user holds.

## License

MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Marcel Kummerow.