Repository navigation
Client Setup
This page covers the common ways to connect MCP clients and HTTP clients to ProxmoxMCP-Plus.
For Claude Code, follow Read-only Proxmox MCP with Claude Code to connect with a Proxmox audit token and query node and guest status.
| Client or use case | Recommended pattern | Target |
|---|---|---|
| Claude Desktop | MCP stdio | local uvx proxmox-mcp-plus or source checkout |
| Cursor | MCP stdio, or Streamable HTTP if hosted separately | local command or http://<host>:8000/mcp
|
| VS Code / GitHub Copilot agent mode | MCP stdio, or Streamable HTTP where supported | local command or remote MCP endpoint |
| Codex | MCP stdio | local command configured in Codex MCP settings |
| OpenCode | MCP stdio with env file | examples under proxmox-config/opencode/
|
| Open WebUI | MCP Streamable HTTP or OpenAPI |
/mcp or /openapi.json
|
| HTTP-only tools | OpenAPI bridge |
http://<host>:8811/docs and /openapi.json
|
| Remote MCP clients | MCP Streamable HTTP | http://<host>:8000/mcp |
Use MCP stdio when the client can launch the server locally. Use MCP Streamable HTTP when the server runs on another host. Use OpenAPI when the consumer only understands HTTP or Swagger-style schemas.
Use these buttons only if your client supports MCP install deeplinks.
This config works for MCP clients that launch local server processes:
{
"mcpServers": {
"proxmox-mcp-plus": {
"command": "uvx",
"args": ["proxmox-mcp-plus"],
"env": {
"PROXMOX_HOST": "your-proxmox-host",
"PROXMOX_USER": "root@pam",
"PROXMOX_TOKEN_NAME": "mcp-token",
"PROXMOX_TOKEN_VALUE": "your-token-secret",
"PROXMOX_PORT": "8006",
"PROXMOX_VERIFY_SSL": "true",
"LOG_LEVEL": "INFO"
}
}
}
}If the repo is cloned locally and you want file-based config:
{
"mcpServers": {
"proxmox-mcp-plus": {
"command": "uvx",
"args": ["proxmox-mcp-plus"],
"env": {
"PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json"
}
}
}
}For source checkouts that launch main.py directly:
{
"mcpServers": {
"proxmox-mcp-plus": {
"command": "python",
"args": ["/absolute/path/to/ProxmoxMCP-Plus/main.py"],
"env": {
"PYTHONPATH": "/absolute/path/to/ProxmoxMCP-Plus/src",
"PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json"
}
}
}
}An example Claude Desktop config is included at:
proxmox-config/claude_desktop_config.example.json
Typical workflow:
- Create and populate
proxmox-config/config.json. - Update the example paths to your local machine.
- Add the server entry to Claude Desktop's MCP config.
- Restart Claude Desktop.
- Confirm read-only tools such as
get_nodes,get_vms, andget_storageappear.
Cursor can use the stdio config above. After adding the server, refresh the MCP server list and verify that read-only tools appear before running mutating workflows.
If the server is hosted remotely, run the Docker Streamable HTTP service and connect Cursor to:
http://<docker-host>:8000/mcp
Use the install button above if your VS Code build supports MCP install deeplinks. Otherwise add the stdio config manually in the MCP server settings used by your VS Code agent extension.
For a remote Streamable HTTP deployment, use:
{
"type": "http",
"url": "http://<host>:8000/mcp"
}Use the stdio config with uvx proxmox-mcp-plus. Prefer a config file path when you already have proxmox-config/config.json checked and validated locally.
Minimal server shape:
[mcp_servers.proxmox-mcp-plus]
command = "uvx"
args = ["proxmox-mcp-plus"]
[mcp_servers.proxmox-mcp-plus.env]
PROXMOX_MCP_CONFIG = "/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json"Examples for OpenCode live under:
proxmox-config/opencode/
The example command sources environment variables and then launches the package. This is useful when you want to avoid hard-coding credentials in JSON.
For HTTP-native clients, run the OpenAPI bridge:
export PROXMOX_API_KEY="${PROXMOX_API_KEY:-$(openssl rand -hex 32)}"
docker compose up -dThen connect to:
| Route | Purpose |
|---|---|
http://<host>:8811/docs |
Swagger UI |
http://<host>:8811/openapi.json |
OpenAPI schema |
http://<host>:8811/livez |
unauthenticated liveness |
http://<host>:8811/readyz |
authenticated readiness |
http://<host>:8811/health |
authenticated readiness alias |
Send authenticated requests with:
Authorization: Bearer <PROXMOX_API_KEY>
After connecting any client:
- Confirm the server starts without config validation errors.
- Confirm read-only tools appear:
get_nodes,get_vms,get_containers,get_storage. - In OpenAPI mode, confirm
/livezreturns200. - In OpenAPI mode, confirm authenticated
/healthor/readyzis healthy. - Confirm
execute_container_commandappears only if the config includes ansshsection. - Run mutating tools only after checking target IDs, storage, permissions, and command policy.
-
uvxis not installed or not on PATH. -
PYTHONPATHis missing when launching from a source checkout. -
PROXMOX_MCP_CONFIGpoints to the wrong file. - The Proxmox API token lacks permissions for the requested operation.
- TLS verification is disabled but
PROXMOX_DEV_MODEorsecurity.dev_modeis not enabled. - A client points to
http://<host>:8811expecting MCP Streamable HTTP; usehttp://<host>:8000/mcpinstead. -
execute_container_commandis expected even though thesshconfig is absent.