Harryc6/ProxmoxMCP

last_reviewed: 2025-11-28

Proxmox MCP integration

Overview

This project implements a read-only Model Context Protocol (MCP) server for the Proxmox cluster so that agents can pull live information about nodes, guests, and storage and use it to keep lab documentation up to date.

The MCP server exposes a small set of tools that query the Proxmox HTTP API and return structured data about:

• Cluster nodes (names, CPU/RAM, status, IPs).
• LXC containers and VMs (placement, type, HA group).
• Storage (local ZFS tank pools and any NFS storage).

Architecture

• MCP server: a small Node.js CLI (proxmox-mcp-server) that speaks MCP over stdin/stdout to the client.
• Proxmox API: accessed over HTTPS using a dedicated, read-only API token (for example, a user with the PVEAuditor role).
• Client configuration: the MCP-aware client (for example, Codex) spawns the MCP server on demand and provides Proxmox connection details via environment variables.

Environment variables:

• PROXMOX_API_URL: https://proxmox-g4:8006
• PROXMOX_API_TOKEN_ID: token ID (for example root@pam!mcp-docs)
• PROXMOX_API_TOKEN_SECRET: token secret
• PROXMOX_TLS_INSECURE: set to 1 to skip TLS verification (for example, when using a self-signed certificate).

The server implements:

• initialize: negotiates protocolVersion and advertises tool capabilities.
• tools/list: returns the available tools with descriptions and JSON input schemas.
• tools/call: executes a named tool with structured arguments.
• notifications/initialized: treated as a notification (no response).

Tools

Tools currently exposed:

• list_nodes
  • Description: list Proxmox nodes with basic specs and status.
  • Backed by: GET /cluster/resources?type=node.
• list_guests
  • Description: list VMs and LXCs, optionally filtered by node.
  • Backed by: GET /cluster/resources?type=vm.
• list_storage
  • Description: list storage pools across the cluster.
  • Backed by: GET /cluster/resources?type=storage.
• list_ha_resources
  • Description: list HA-managed resources and their groups.
  • Backed by: GET /cluster/ha/resources.

TODO: Add a summarising resource (for example proxmox://cluster/summary) that aggregates node, guest, and storage information into a single view the agent can drop into [[Proxmox Cluster]] and [[Network Topology]].

Goals And Scope

Primary goals:

• Provide a read-only Proxmox MCP server that can:
  • List cluster nodes, their specs, and IPs.
  • List LXCs and VMs with node placement and HA membership.
  • List storage pools, especially local ZFS tank and any NFS storages.
• Use MCP outputs to keep [[Proxmox Cluster]] and [[Network Topology]] in sync with the actual cluster.
• Reflect real HA replication behaviour and, later, proper backup routines in [[Backup Strategy Runbook]].

Non-goals (for now):

• Orchestrating workloads (starting/stopping/migrating guests) via MCP.
• Changing Proxmox configuration (creating or deleting resources).
• Exposing secrets or credentials from Proxmox within this vault.

Key Decisions

2025-11-26 – Read-Only Proxmox MCP Scope

• Initial server is strictly read-only, exposing tools that list nodes, guests, storage, and HA resources but do not mutate anything.
• Authentication uses a dedicated read-only API token (for example, PVEAuditor), not a full administrative account.

2025-11-26 – Co-Locating MCP With Lab Access

• Short term: the server may run on the main workstation for simplicity.
• Long term: preferred placement is a dedicated management LXC/VM inside the Proxmox cluster, reachable via SSH from the workstation.
• Client configuration should support both proxmox-mcp-server locally and ssh mcp-mgmt proxmox-mcp-server for a management LXC.

Configuration Example (Codex)

To register the server with Codex:

codex mcp add proxmox-mcp-server \
  --env PROXMOX_API_URL='https://proxmox-g4:8006' \
  --env PROXMOX_API_TOKEN_ID='root@pam!mcp-docs' \
  --env PROXMOX_API_TOKEN_SECRET='REDACTED' \
  -- node "/.../proxmox-mcp/bin/proxmox-mcp-server.js"

Then start Codex from the vault root:

codex -C "/.../Home Vault"

Codex will:

• Call initialize, then send notifications/initialized.
• Call tools/list to discover available tools.
• Use tools/call to invoke list_nodes, list_guests, list_storage, or list_ha_resources.

Status

2025-11-26 – Current State

• Proxmox cluster topology, HA workloads, and storage (local ZFS tank and NAS NFS shares) are documented in:
  • [[Proxmox Cluster]]
  • [[Network Topology]]
  • [[NAS]]
  • [[Backup Strategy Runbook]]
• Desired MCP tools and integration points are outlined in:
  • [[Lab Projects and TODOs]]
  • This README.
• A Node.js MCP server (proxmox-mcp-server) is implemented with tools list_nodes, list_guests, list_storage, and list_ha_resources, and has been smoke-tested locally against the lab Proxmox API.

Outstanding Work

Based on the current status:

• Move the MCP server towards its preferred long-term placement (a management LXC/VM), while keeping local runs possible via SSH.
• Ensure a dedicated, read-only Proxmox API token exists for this MCP server and is documented in the password manager (not in this vault).
• Document and standardise how agents should call these tools to refresh:
  • [[Proxmox Cluster]]
  • [[Network Topology]]
  • [[Backup Strategy Runbook]]
• Capture example MCP client configuration and, optionally, a short runbook entry under [[Lab Projects and TODOs]].

Open questions:

• How strict TLS verification should be for the Proxmox API (self-signed CA versus a trusted certificate).
• Whether per-environment configs are needed (for example lab versus future staging) or a single lab-focused configuration is sufficient.

Security Considerations

• Use a dedicated API token limited to read-only permissions (for example, PVEAuditor), not a full administrative account.
• Store secrets in environment variables or a password manager, never directly in this vault.
• Do not expose tools that mutate Proxmox state (start/stop/destroy) in the initial version. If needed later, keep them in a separate admin-only MCP configuration.

Documentation integration

The Proxmox MCP server will primarily support:

• [[Proxmox Cluster]]: keeping node lists, HA placements, and ZFS/NFS storage details accurate.
• [[Network Topology]]: validating node IPs and roles.
• [[Backup Strategy Runbook]]: reflecting real HA replication and later, proper backup workflows once the Backups NFS share is in use.

For project-level tracking of remaining work, see the Outstanding Work section above.