Skip to content

Read only Proxmox MCP with Open WebUI

RekklesNA edited this page Nov 14, 2026 · 1 revision

Read-only Proxmox MCP with Open WebUI

Open WebUI can list the VMs, LXCs and nodes in a Proxmox lab through its built-in MCP connection. The setup below uses Streamable HTTP and a dedicated Proxmox audit token. The MCP endpoint stays on a private Docker network.

Tested with Open WebUI 0.13.3 and ProxmoxMCP-Plus 0.7.0. See the test results at the end of the page.

Configure ProxmoxMCP-Plus

Create a privilege-separated API token for a dedicated Proxmox user. For a lab-wide inventory, grant the user and the token the PVEAuditor role at / with propagation. Save the Proxmox hostname, token identity and secret in a private JSON file named proxmox-readonly.json. Set verify_ssl to true. The Claude Code guide shows the proxmox and auth fields and explains both ACLs.

Use this mcp section in the JSON file.

{
  "transport": "STREAMABLE_HTTP",
  "host": "0.0.0.0",
  "port": 8000,
  "allowed_hosts": ["proxmox-mcp:8000"],
  "tool_allowlist": ["get_nodes", "get_vms", "get_containers"]
}

On the Docker host, join Open WebUI and ProxmoxMCP-Plus to the same user-defined network. The example assumes an existing Open WebUI container named open-webui. Run the first line once to create the network. Put a new, random MCP_API_KEY in a private mcp-http.env file in the current directory.

docker network create proxmox-webui
docker network connect proxmox-webui open-webui
docker run -d --name proxmox-mcp --network proxmox-webui   --env-file ./mcp-http.env   -e PROXMOX_MCP_MODE=mcp-http   -e PROXMOX_MCP_CONFIG=/config/proxmox-readonly.json   --mount type=bind,source="$PWD/proxmox-readonly.json",target=/config/proxmox-readonly.json,readonly   ghcr.io/rekklesna/proxmoxmcp-plus:0.7.0

If your Proxmox API uses a private CA, mount the trusted CA bundle in the MCP container and point REQUESTS_CA_BUNDLE at its path inside the container. Use a Proxmox DNS name that matches its certificate.

Add the connection in Open WebUI

  1. As an admin, open Settings → Admin → Integrations → External Tool Servers and add a connection.
  2. Select MCP (Streamable HTTP). Set the URL to http://proxmox-mcp:8000/mcp. Open WebUI reaches this address from its container. Use the same hostname and port in the server's allowed_hosts.
  3. Select Bearer and enter the MCP_API_KEY from the environment file. The Proxmox token secret stays in the MCP server configuration.
  4. Verify the connection and save it. The verification should discover get_nodes, get_vms and get_containers.
  5. In a chat with a model that supports tools, enable the connection under + → Tools. Try “List offline Proxmox nodes and stopped VMs and LXCs. Include each guest's ID and node, and report failed queries separately.”

If Open WebUI cannot verify the connection, check the shared Docker network, the full /mcp path and the Bearer key. Successful verification checks MCP discovery. If discovery works but an inventory call fails, check the upstream Proxmox TLS certificate and the permissions of both the Proxmox user and token.

Test results

Open WebUI's verification endpoint accepted the configured key, returned the three expected schemas and saved the connection. With a wrong key, ProxmoxMCP-Plus returned HTTP 401 and Open WebUI reported a verification failure. Open WebUI's built-in MCP client then called all three tools against a local Proxmox API fixture. It returned an offline node (pve-lab-b), a stopped VM (build-runner, ID 101) and a stopped LXC (media-cache, ID 203).

This test covered connection, authentication, and tool calls using a simulated Proxmox API. Model-driven chat output depends on the model you select.

Open WebUI MCP documentation · ProxmoxMCP-Plus v0.7.0

Clone this wiki locally