Proxmox MCP is an opinionated MCP server

Proxmox MCP Server

NOTE:

This project is under active development.

Motivation

Modern infrastructure often uses tools such as Terraform/OpenTofu, Ansible, and GitOps. These tools deploy and configure Proxmox infrastructure and Kubernetes clusters.

The Proxmox MCP Server does not replace these tools. It gives AI assistants and automation agents access to information about your Proxmox clusters.

The default tools are read-only. Optional action tools can be enabled with --allow-destructive for operations such as backups and reboots.

Instead of checking many pages in the Proxmox UI or running several commands, you can ask an AI assistant to collect and analyze the required information. Your existing automation tools remain the main source for infrastructure changes.

Overview

The server connects an MCP client, such as an AI assistant, to the Proxmox VE API. It supports multiple Proxmox clusters and returns structured data.

You can use it to:

• inspect clusters, nodes, and storage
• check resource usage and node status
• review recent Proxmox task events
• find differences and possible configuration problems
• collect information before you make infrastructure changes

Keep your AI on the leash.

Proxmox core tools

The MCP server provides the following read-only tools:

Use proxmoxclusterslist first to find the cluster names used by the other tools. MCP clients can discover the full input and output schemas. You can also list the tools from the command line:

proxmox-mcp tools --config /absolute/path/to/cluster-config.yaml

When --allow-destructive is enabled, proxmoxvmsbackup and proxmoxcontainersbackup accept cluster, vmid, optional node, storage, mode, and compress arguments. They start an asynchronous backup and return its Proxmox task identifier; task creation does not mean that the backup has already completed successfully.

Installation

For a local installation with Homebrew, run:

brew install sergelogvinov/tap/proxmox-mcp

You do not need a local installation when you use an MCP server hosted on another machine.

Configure Proxmox clusters

Create a YAML file that contains one or more Proxmox clusters:

clusters:
  - region: homelab
    url: https://pve.example.com:8006/api2/json
    token_id: mcp@pve!reader
    token_secret_file: /absolute/path/to/token-secret
    ca_file: /absolute/path/to/proxmox-ca.crt

Each cluster supports these fields:

Shortened. The full README is on GitHub.