home / mcp / proxmox mcp openapi server

Proxmox MCP OpenAPI Server

MCP to manage Proxmox VMs in Cursor

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "agentify-sh-cursor-proxmox-mcp": {
      "command": "python",
      "args": [
        "-m",
        "proxmox_mcp.server"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "PROXMOX_HOST": "pve.example.com",
        "PROXMOX_PORT": "8006",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_SERVICE": "PVE",
        "PROXMOX_MCP_CONFIG": "path/to/proxmox-config/config.json",
        "PROXMOX_TOKEN_NAME": "mcp-token",
        "PROXMOX_VERIFY_SSL": "false",
        "PROXMOX_TOKEN_VALUE": "TOKEN_VALUE"
      }
    }
  }
}

You are running an MCP server that integrates Cursor with Proxmox to manage VMs, containers, storage, and cluster status through a production‑ready REST API and Open WebUI. This server enables you to create and control VMs, manage containers, monitor health, and execute console commands, all via MCP tools and endpoints.

How to use

You interact with the Proxmox MCP Server by running it locally (or as a service) and then talking to its OpenAPI REST endpoints from your MCP client or Open WebUI. You can create VMs, start/stop/shutdown/reset them, delete VMs, list containers, query nodes and storage, monitor cluster health, and run commands inside running VMs. The API mirrors common Proxmox actions but is exposed through a stable MCP surface for integration with Cursor and other tooling.

How to install

Prerequisites and initial setup stay focused on getting a working MCP server that talks to Proxmox and serves OpenAPI endpoints.

Configuration and usage notes

Configure the MCP server to connect to Proxmox using API tokens, and set up environment variables to control runtime behavior and config paths. The server offers 11 endpoints for VM, container, and cluster management, along with OpenAPI REST integration for external automation.

Additional setup and security

Set up Proxmox API tokens with appropriate permissions, enable API access, and secure the OpenAPI service behind authentication or a reverse proxy as needed. Maintain a dedicated configuration file for Proxmox MCP and ensure your environment variables point to that file.

Troubleshooting

If you encounter port conflicts, configuration errors, or connectivity issues, verify the OpenAPI service port, ensure Proxmox is reachable on its API URL, and check logs for authentication or connection errors.

Notes on usage patterns

For development and testing, run the MCP server directly with Python and test against the local OpenAPI endpoints. For production, run the OpenAPI service alongside the MCP server and expose the REST API through your chosen deployment (Docker, Kubernetes, or a systemd service).

Available tools

create_vm

Create a new virtual machine with specified resources on a chosen Proxmox node.

delete_vm

Delete a virtual machine, with an option to force delete.

start_vm

Start a virtual machine.

stop_vm

Force stop a virtual machine.

shutdown_vm

Gracefully shut down a virtual machine.

reset_vm

Restart a virtual machine.

get_containers

List all LXC containers and their status.

get_nodes

List all nodes in the Proxmox cluster.

get_node_status

Get detailed status for a specific node.

get_vms

List all VMs across the cluster.

get_storage

List available storage pools.

get_cluster_status

Get overall cluster health status.

execute_vm_command

Execute a command inside a VM via QEMU Guest Agent.