Repository navigation
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.
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.0If 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.
- As an admin, open Settings → Admin → Integrations → External Tool Servers and add a connection.
- 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'sallowed_hosts. - Select Bearer and enter the
MCP_API_KEYfrom the environment file. The Proxmox token secret stays in the MCP server configuration. - Verify the connection and save it. The verification should discover
get_nodes,get_vmsandget_containers. - 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.
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.