# Reported issues for mcp-proxmox

Pod holds 7 of 7 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [mcp-proxmox](/mcp/mcp-proxmox).

## Most discussed

### Broken with mcp 2.0.0: ModuleNotFoundError: No module named 'mcp.server.fastmcp'

## Summary

As of `mcp` 2.0.0, `mcp-proxmox` fails to start. `server.py` imports
`FastMCP` from `mcp.server.fastmcp`, which no longer resolves on the 2.x
line. Since `pyproject.toml` declares `mcp>=1.26.0` with no upper bound,
every fresh resolve now picks 2.0.0 and crashes on import.

This hits `uvx mcp-proxmox` hardest, because it re-resolves dependencies
on every launch. Setups that worked yesterday break with no change on the
user's side. In Claude Desktop this surfaces only as "Server disco

[Read the thread](https://github.com/antonio-mello-ai/mcp-proxmox/issues/13) · 2026-07-30 · closed · external user · 1 comment

### Migrate to MCP Python SDK 2.x server API

## Context

`mcp` 2.0.0 (2026-07-28) removed `mcp.server.fastmcp`, which `src/mcp_proxmox/server.py` imports. v1.2.2 (#14) pinned `mcp>=1.26.0,<2` as the interim fix so fresh installs work again (#13).

## Task

Move the server to the 2.x API so the pin can be lifted:

- Replace `from mcp.server.fastmcp import FastMCP` with the 2.x equivalent (`mcp.server.MCPServer` / `mcp.server.mcpserver`) and adapt tool registration.
- Keep the 34 tools and their signatures unchanged; `tests/test_server.py` m

[Read the thread](https://github.com/antonio-mello-ai/mcp-proxmox/issues/15) · 2026-08-17 · open · 0 comments

### Add unit tests for the ProxmoxClient wrapper and VMID resolution

The test suite covers the tool layer (`test_provisioning.py`, `test_lifecycle.py`, etc.) but `client.py` itself — the thin wrapper that builds every proxmoxer API path — is not directly tested. Helpers like `find_guest` (which scans `get_cluster_resources` to resolve a VMID to its node and guest type) and the qemu-vs-lxc path branching in methods like `guest_action`, `get_snapshots`, and `migrate_guest` are exactly the kind of code where a wrong path string silently breaks a tool. The mock fixtu

[Read the thread](https://github.com/antonio-mello-ai/mcp-proxmox/issues/7) · 2026-06-04 · open · 0 comments

### Add a Troubleshooting section to the README

The README covers setup and the full tool list well, but there is no troubleshooting guidance. The most common friction points are predictable and the failure modes are already visible in the code: a token without the right privilege returns a 403, `exec_command` fails when `qemu-guest-agent` is not running (and is unsupported for LXC by Proxmox), self-signed certificates require `PROXMOX_VERIFY_SSL=false`, and the config raises a clear error when required env vars are missing. A short Troublesh

[Read the thread](https://github.com/antonio-mello-ai/mcp-proxmox/issues/6) · 2026-06-04 · open · 0 comments

### Add cluster health and HA status tools (quorum, corosync, HA resources)

The server covers individual nodes (`list_nodes`, `get_node_status`) and per-guest operations, but has no cluster-wide health view. Before doing anything risky on a multi-node cluster — a live migration, a rolling reboot, a backup window — the natural first question is "is the cluster healthy and quorate?". Today an assistant cannot answer that. This formalizes the "Cluster status" item already noted in ROADMAP.md into concrete scope.

**Scope**
- `get_cluster_status` — quorum state, node member

[Read the thread](https://github.com/antonio-mello-ai/mcp-proxmox/issues/5) · 2026-06-04 · open · 0 comments

### Add retry/backoff and consistent error normalization in the API client

The `ProxmoxClient` wraps `proxmoxer` directly with a fixed 30s timeout and no retry logic. Transient failures common against a Proxmox endpoint — a node briefly returning 5xx during load, a TLS reset, a request timing out mid-migration — surface as raw exceptions or partial failures. Most tools also let exceptions bubble up unstructured (only `exec_command` catches and normalizes them), so the assistant sees inconsistent error shapes across tools.

**Scope**
- Add bounded retry with exponential

[Read the thread](https://github.com/antonio-mello-ai/mcp-proxmox/issues/4) · 2026-06-04 · open · 0 comments

### Add a task tracking tool to follow long-running operations to completion

Almost every mutating tool (`create_vm`, `clone_guest`, `migrate_guest`, `create_backup`, `restore_backup`, `create_snapshot`, lifecycle actions) returns a Proxmox task UPID immediately and exits — the operation is fire-and-forget. The client already has `get_task_status(node, upid)`, but it is not surfaced as a tool, so an assistant has no way to know whether a clone finished, a migration succeeded, or a backup errored out. For a natural-language workflow ("clone VM 100 and then start it") this

[Read the thread](https://github.com/antonio-mello-ai/mcp-proxmox/issues/3) · 2026-06-04 · open · 0 comments

## Most recent

The remaining reports are on [the project's issue tracker](https://github.com/antonio-mello-ai/mcp-proxmox/issues).