Proxmox MCP

Proxmox MCP is an MCP server for Proxmox VE. It lets MCP clients manage VMs, containers, storage, backups and more through the Proxmox API, authenticated with API tokens.

Highlights

• 77 tools in 14 categories: VMs and containers, storage, backups, snapshots, networking, firewall, HA, pools, tasks, access rights, and a generic API access with schema lookup.

• Several independent Proxmox hosts or clusters in one settings file, with a default host.

• Token secrets from the OS keychain, Bitwarden Secrets Manager, 1Password, Vault or OpenBao, pass, an environment variable, a file, or your own command.

• TLS certificate verification on by default, with a CA file or SHA-256 fingerprint pinning.

• Read-only mode, globally or per host.

• One settings file (YAML) that lists every category and tool, so each one can be switched on or off.

• Confirmation before destructive actions, when the MCP client supports it.

• Setup assistant: npx proxmox-ve-mcp setup.

Related MCP server: Proxmox MCP Bridge

Quick start

1. In Proxmox VE, create a user and an API token with privilege separation. Grant the token only the rights the agent needs. The steps are in docs/permissions.md.

2. Run the setup assistant. It checks the server certificate, asks for the token and where its secret is stored, tests the connection and writes the settings file.

   npx proxmox-ve-mcp setup

3. Connect your MCP client. For Claude Code, run:

   claude mcp add --transport stdio proxmox -- npx -y proxmox-ve-mcp

   For the other clients see Connect your client, or run npx proxmox-ve-mcp client-config <client>.

4. Check the setup:

   npx proxmox-ve-mcp doctor

Connect your client

npx proxmox-ve-mcp client-config <client> prints the snippet for a client and says where it goes. The snippets below match that output in a more compact form. If the file already has other servers, add only the proxmox entry.

Claude Code runs the one-line command from the quick start. Add --scope user before proxmox to use the server in every project.

Claude Desktop config file: ~/.config/Claude/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows. Restart Claude Desktop afterwards.

{
  "mcpServers": {
    "proxmox": { "command": "npx", "args": ["-y", "proxmox-ve-mcp"] }
  }
}

Cursor config file: ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one project.

{
  "mcpServers": {
    "proxmox": { "type": "stdio", "command": "npx", "args": ["-y", "proxmox-ve-mcp"] }
  }
}

VS Code config file: .vscode/mcp.json in the workspace. The key is servers, not mcpServers.

{
  "servers": {
    "proxmox": { "type": "stdio", "command": "npx", "args": ["-y", "proxmox-ve-mcp"] }
  }
}

Codex config file: ~/.codex/config.toml. Or run codex mcp add proxmox -- npx -y proxmox-ve-mcp.

[mcp_servers.proxmox]
command = "npx"
args = ["-y", "proxmox-ve-mcp"]

Windsurf config file: ~/.codeium/windsurf/mcp_config.json. Restart Windsurf or refresh the MCP servers afterwards.

{
  "mcpServers": {
    "proxmox": { "command": "npx", "args": ["-y", "proxmox-ve-mcp"] }
  }
}

Configuration

The settings file is YAML. The server looks for it in this order:

1. --config <path> on the command line, or the PROXMOX_MCP_CONFIG environment variable.

2. The default location: ~/.config/proxmox-ve-mcp/config.yaml on Linux and macOS (below $XDG_CONFIG_HOME if set), %APPDATA%\proxmox-ve-mcp\config.yaml on Windows.

Example with two hosts and a few switches:

version: 1
defaultHost: lab
categories:
  ha:
    enabled: false
  api:
    tools:
      pve_api_request: false
hosts:
  lab:
    description: Lab cluster
    url: https://pve-lab.example.com:8006
    tokenId: mcp@pve!agent
    tokenSecret:
      source: keyring
  prod:
    description: Production cluster, read-only for this server
    url: https://pve-prod.example.com:8006
    tokenId: mcp@pve!agent
    tokenSecret:
      source: bws
      secretId: 00000000-0000-0000-0000-000000000000
    tls:
      caFile: /etc/proxmox-mcp/pve-prod-ca.pem
    readOnly: true

Unknown keys stop the server at startup, so typos are not ignored. npx proxmox-ve-mcp config validate checks the file. The server also runs without a file when PROXMOX_URL, PROXMOX_TOKEN_ID and PROXMOX_TOKEN_SECRET or PROXMOX_TOKEN_SECRET_FILE are set. All fields, the TLS modes and the environment variables are in docs/configuration.md.

Secrets

Each host reads its token secret from one source. The secret is resolved on first use and is never written to logs, tool output or error messages.

Details and the rules of each source: docs/secrets.md.

Safety

• Read-only: readOnly: true at the top level, or PROXMOX_MCP_READ_ONLY=1, removes all write and destructive tools. Per host, readOnly: true refuses write and destructive calls to that host, and the other hosts still accept them.

• Categories and tools: whole categories or single tools can be switched off in the settings file. A switched-off tool is not registered, so the client never sees it.

• Confirmation: confirmDestructive is auto by default and asks the user when the client supports it. always refuses destructive calls when the client cannot ask. never runs them without asking.

• Token rights: the API token is the real boundary. The server cannot do more in Proxmox than the token is allowed to do. See docs/permissions.md.

• TLS: certificate checks stay on by default. For self-signed certificates use tls.caFile or tls.fingerprint.

The threat model and the known risks are in SECURITY.md.

Tools

Each tool has an access level: R (read), W (write) or D (destructive). The parameters of every tool are in docs/tools.md.

CLI

proxmox-ve-mcp [--config <path>]          start the MCP server on stdio (what MCP clients run)
proxmox-ve-mcp <command> [options]

setup                                     interactive setup: host, TLS, token, secret store, client snippet
host list|add|edit|remove|test [alias]    manage Proxmox hosts
secret set <alias> [--stdin]              store or replace a token secret in the OS keychain
tools [--json]                            list categories and tools with access level and state
config path|validate|sync|edit            work with the settings file
doctor [alias]                            check settings, secrets, TLS, connection and permissions
client-config <client> [--name <n>]       print the snippet for an MCP client
help [command]                            show help, also: <command> --help

--config <path> works with every command. -v or --version prints the version. Options such as --json, --yes, --delete-secret, --use-keyring and --dry-run are listed by proxmox-ve-mcp help <command>.

Docker

docker build -t proxmox-ve-mcp .

Env-only mode, without a settings file:

docker run -i --rm \
  -e PROXMOX_URL=https://pve.example.com:8006 \
  -e PROXMOX_TOKEN_ID='mcp@pve!agent' \
  -e PROXMOX_TOKEN_SECRET_FILE=/run/secrets/pve-token \
  -v /path/to/pve-token:/run/secrets/pve-token:ro \
  proxmox-ve-mcp

Or mount a settings file and the secret files it refers to:

docker run -i --rm \
  -e PROXMOX_MCP_CONFIG=/config/config.yaml \
  -v /path/to/config.yaml:/config/config.yaml:ro \
  -v /path/to/secrets:/run/secrets:ro \
  proxmox-ve-mcp

The container has no OS keychain, so the keyring source does not work there. Use env, file or a secret manager reference instead.

Development

See CONTRIBUTING.md for the setup, the project layout and how to add a tool.

License

MIT. See LICENSE.