AI Server

All clusters

Model Context Protocol (MCP) endpoint that lets AI assistants query the cluster, manage VMs and automate operations through natural language.

Features

AI Assistant Integration

Manage Proxmox infrastructure through natural language via AI assistants.

Data Access

AI tools can query VM status, cluster health, and resource usage.

Automated Tasks

AI assistants can perform VM management, snapshot creation, and monitoring.

MCP Protocol

Uses Model Context Protocol for AI integration.

AI Tool Connection

Connect AI assistants to Proxmox environments.

Access Control

Controlled API exposure for secure AI interaction.

Why

Why an MCP server when the PVE API is already there?

Talk to the cluster in English

Ask "which VMs use the most memory on pve01?" instead of writing the API call. Lower the barrier for everyone on the team.

Cluster context already loaded

The MCP server knows about every cluster you configured: the AI doesn't have to discover, authenticate or paginate the PVE API itself.

Multi-cluster from one connection

One AI assistant reaches every cluster in cv4pve-admin on which its token has permissions. No separate token or hostname for each cluster.

Permission-aware

cv4pve-admin checks every tool call against the permissions of the AI Server token, per tool and per cluster. It refuses a tool the token is not granted.

Sections

Overview: introduction to the module
API Access: lists the tokens that can call the MCP tools (name, active flag, creation and expiry date). Select one to Regenerate its key or to see its Effective Permissions. The page shows a warning when the MCP server is disabled, and an alert when a call with an invalid key is rejected
Bridge: download the cv4pve-mcp-bridge binary for your platform (Windows x64, Linux x64 and ARM64, macOS Intel and Apple Silicon). The page also provides a ready-to-use claude_desktop_config.json for stdio-only clients (Claude Desktop)

Connecting AI Clients

First-time setup

Before connecting any AI client, enable the endpoint and generate the API key:

Open the AI Server module, open its settings and turn on Enabled (the endpoint is off by default)
Go to the API Access tab
Select the AI Server token, click Regenerate and confirm: the previous key stops working
Copy the key: clients send it in the X-API-Key header (see below)

Copy the key now: The API key is shown only once after generation. Copy it before closing the dialog.

MCP endpoint URL

The MCP endpoint is exposed at:

https://<your-server>/mcp

Clients authenticate by sending the AI Server token (from the API Access tab) in the X-API-Key HTTP header. A missing or invalid key returns 401; 503 means the AI Server module is disabled. After too many invalid keys from one address in a minute, a further invalid key returns 429 with Retry-After: 60 until the minute is over. The limit is Security:MaxAttemptsPerMinute (default 10). A valid key is never counted and is never refused by the limit.

Native HTTP clients

Clients that support MCP over HTTP/SSE natively (Cursor, Windsurf, Zed, Claude Code, etc.) connect directly with the URL above and the X-API-Key header. They need no additional software.

Claude Desktop and stdio-only clients

Claude Desktop only supports stdio transport and cannot connect to HTTP MCP servers directly. Use cv4pve-mcp-bridge to proxy stdio ↔ HTTP. Download, options and the Claude Desktop configuration are in MCP Bridge.

Available Tools

AI Server exposes 29 tools grouped by area, plus 2 additional Enterprise tools for SQL-like queries. Every tool except ListClusters takes the name of the cluster to work on as cluster_name. ListClusters returns the names of the enabled clusters the token can work on.

The full list, with what each tool does and its parameters, is in Tools.

Output Format

The Output Format setting controls how the tables returned by the tools (lists of guests, nodes, storages, query results) are serialized before being sent to the AI model. Choosing the right format reduces the text the AI model has to read (counted in model tokens, not to be confused with the API tokens of this module) and improves response quality.

These results are always JSON, whatever the setting:

A single object, such as a status or a configuration
The result of an action
The historical metrics (ListVmRrdData, ListNodeRrdData)
ListBackupJobs

The table below shows the same request returned in each format, with approximate token counts as an example.

Format	Description	Approx. tokens*
JsonCompact	JSON with `headers` + `rows` arrays	~340 (about 43% fewer than JsonNormal)
JsonNormal	Standard JSON array of objects	~600
Toon	Token-Oriented Object Notation (`data[23]{...}`)	~335 (about 44% fewer than JsonNormal)
Csv	Plain CSV with header row	~320 (about 47% fewer than JsonNormal)

*Approximate values for the same response payload, in proportion to a measure made on 30 rows of cluster resources: actual token count depends on the data and on the model.

The default is JsonCompact, which offers a good balance between token efficiency and compatibility with all AI models.

Choosing the right format:

Use Toon or Csv to minimize token usage with large datasets.
Use JsonNormal if your AI client has trouble parsing compact formats.
Most AI models work well with the default JsonCompact.

Example Prompts

Real prompts you can paste into your AI assistant once the MCP endpoint is connected. The assistant picks the right tool(s) and chains them automatically.

Read-only inspection

Which VMs in cluster home-lab are currently running and using more than 70% CPU?

Show me the snapshots older than 30 days across all clusters.

Summarise the health of cluster prod: nodes online/offline, VM status counts, free storage per pool.

List the last 20 failed tasks across the cluster, with user and duration.

For node pve01, show the CPU and memory pressure (PSI) over the last 24 hours.

Backup / storage management

List all backups for VM 101 and tell me the most recent one.

On node pve01, storage local, list the ISO images by size and propose which to delete.

Download the latest Debian 12 netinst ISO to storage local on node pve01.

Show me all backup jobs with their schedule and the guests each one covers.

Operations (write actions)

Create a snapshot of VM 200 called pre-upgrade with description “before kernel update”, including RAM.

Migrate VM 105 from pve01 to pve02, live migration if running.

Run a backup of VM 200 on storage pbs-main with zstd compression.

Reset VM 150 (it’s hung).

Advanced queries

Enterprise adds the GetQuerySchema + ExecuteQuery pair. Useful prompts:

What tables can I query against this cluster?

Group all guests by node and count how many are running vs stopped.

Find the top 5 VMs by memory usage, with their node.

List storages with more than 80% usage.

Application permissions

Each tool has its own permission, with the key AIServer.Tools.<tool name> (for example AIServer.Tools.ListVms). A tool runs only if the token that calls it holds that permission on the cluster named in the call. ListClusters has no permission of its own: it lists the clusters on which the token holds at least one tool permission.

On top of the tool permission, the cluster permissions of the token filter the result. The nodes, guests and storages the token cannot see are left out of the lists, and an action on one of them is refused.

The same filter applies to the lists that are about guests without being lists of guests:

ListTasks returns the tasks of the nodes the token can see. A task about a guest is returned only when the token can see that guest.
ListReplications returns the replication jobs of the guests the token can see.
ListBackupJobs returns a job when it covers at least one guest the token can see, and lists only those guests. A job with no list of guests, such as one for every guest, is returned to a token that can see its node.
The Query tools build every table from the nodes, guests and storages the token can see.

Role	Content
AI Server Tools	Every tool permission except `DownloadIso` and `DeleteIso`. In the Enterprise edition EE also `GetQuerySchema` and `ExecuteQuery`
Admin for module AI Server	The pages, the settings and the tools of the AI Server Tools role

DownloadIso and DeleteIso are in no role, so no token has them until they are given. In the Enterprise Edition EE they are given to a token one by one, in the Permissions tab of the token under Admin Area → Security → App Tokens.

Page and settings permissions:

Permission	Key	Grants
AI Server	`AIServer.Link`	Access to the module and to its Overview page
API Access	`AIServer.Link.api+access`	API Access page
Bridge	`AIServer.Link.bridge`	Bridge page
Edit Settings	`AIServer.EditOptions`	The settings button of the module

The AI Server token is created at the first start. At every start cv4pve-admin assigns it the AI Server Tools role and the cluster Admin role again. Roles and permissions are managed in Admin Area → Security EE.

Proxmox VE privileges: the base (PVEAuditor), plus the privilege of each tool used. It is written in the block of each tool: see the list.

The read-only tools need the base only. ListBackups and ListStorageContent return the backup files only with VM.Backup and Datastore.AllocateSpace.

The base and the rules common to all modules are in Proxmox VE Permissions.

Auditing

Every request to the MCP endpoint is written to the audit log with the name of the token, the tool called and its arguments. A request with an invalid key is logged as a failed authentication, with a short fingerprint of the key, and raises the alert on the API Access page. The requests refused with 429 are not logged and raise no alert.

Settings

Setting	Default	Purpose
Enabled	off	Master on/off switch for the MCP endpoint. While it is off the endpoint answers `503`
Output Format	JsonCompact	How tool responses are serialised before being sent to the AI model: `JsonCompact` · `JsonNormal` · `Toon` · `Csv`