# Proxmox MCP is an opinionated MCP server

Wires an AI assistant into the Proxmox VE API so it can read clusters, nodes, storage, containers and VMs. Useful when clicking through the web UI gets old.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: sergelogvinov
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/sergelogvinov/proxmox-mcp
- Updated: 2026-10-05
- HTML: https://affpapa.org/en/nevibecode/mcp/proxmox-mcp-is-an-opinionated-mcp-server

## What it does

The server links an MCP client to the Proxmox VE API and handles more than one cluster at a time, returning structured data. Every tool starts out read-only: `proxmox_clusters_list`, `proxmox_clusters_describe`, `proxmox_nodes_list`, `proxmox_nodes_describe`, `proxmox_storage_list`, `proxmox_storage_describe`, `proxmox_vms_list`, `proxmox_vms_describe`, `proxmox_containers_list`, `proxmox_containers_describe`, `proxmox_events_list`. Call `proxmox_clusters_list` first, since the other tools take a cluster name from it.

Backups and reboots stay off until you pass `--allow-destructive`, which adds `proxmox_vms_backup` and `proxmox_containers_backup`. Those kick off an asynchronous job and hand back its Proxmox task identifier; a created task is not a finished backup. The server does not take over infrastructure changes — Terraform, Ansible and GitOps keep that job.

You need a YAML file listing your clusters before anything runs. Each entry requires `region` and a `url` ending in `/api2/json`, plus either a token (`token_id` and `token_secret`, or the file variants) or a `username` and `password` pair. Pick one login method per cluster, not both. Point the server at the file with `--config` or the `CONFIG_FILE` variable. The HTTP endpoint ships without user authentication, so access control rests on Proxmox tokens sent in an `Authorization` header.

## Requirements
- Needs: Docker

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add proxmox-mcp-is-an-opinionated-mcp-server -- docker run -i --rm ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0
```

### Codex

**Platform CLI**
```bash
codex mcp add proxmox-mcp-is-an-opinionated-mcp-server -- docker run -i --rm ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "proxmox-mcp-is-an-opinionated-mcp-server": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "proxmox-mcp-is-an-opinionated-mcp-server": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add proxmox-mcp-is-an-opinionated-mcp-server docker run -i --rm ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0
```

## When to use it
- check node and cluster health without opening the web UI
- pull a list of LXC containers with their resource usage
- see how full each storage pool is and what type it is
- scan recent Proxmox tasks across all nodes
- gather facts before touching the infrastructure

## Example prompts
- List my Proxmox clusters and the node status in homelab
- Which VMs are running right now and how much are they using?
- Show the latest tasks for the homelab cluster

## Similar
- [Proxmox VE](https://affpapa.org/en/nevibecode/mcp/proxmox-ve.md) — MCP server · ★ 5
- [proxmox-admin](https://affpapa.org/en/nevibecode/skills/proxmox-admin.md) — skill · 828 installs
- [Proximo — the Proxmox MCP you can hand the keys](https://affpapa.org/en/nevibecode/mcp/proximo-the-proxmox-mcp-you-can-hand-the-keys.md) — MCP server · ★ 61
- [mcp-proxmox](https://affpapa.org/en/nevibecode/mcp/mcp-proxmox.md) — MCP server · ★ 17
- [Proxmox MCP](https://affpapa.org/en/nevibecode/mcp/proxmox-mcp.md) — MCP server · ★ 63
- [ProxmoxMCP-Plus](https://affpapa.org/en/nevibecode/mcp/proxmoxmcp-plus.md) — MCP server · ★ 620

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md