NANDI Proxmox MCP

Turn your Proxmox cluster into an AI-driven platform with 140+ tools for automation, monitoring, and controlled execution.

Open source MCP server for Proxmox VE, powered by NANDI Services.

nandi-proxmox-mcp exposes Proxmox inventory, lifecycle, storage, backup, networking, firewall, access, monitoring, SSH diagnostics, and guarded remote/container operations without removing the safety rails needed for production clusters.

What stays enabled

140+ tools across nodes, cluster, QEMU, LXC, storage, backup, tasks, network, firewall, pools, access, templates, monitoring, and remote operations.
Access tiers: read-only, read-execute, full.
Module split: PVE_MODULE_MODE=core|advanced.
Tool filters: PVE_CATEGORIES, PVE_TOOL_BLACKLIST, PVE_TOOL_WHITELIST.
Destructive guardrails via confirm=true.
Backward-compatible aliases such as listNodes, getVMStatus, startVM, stopContainer.
stdio transport for MCP clients and Streamable HTTP transport for controlled remote deployments.

Required permissions

The server needs two trust channels and both are preserved intentionally:

Proxmox API token
Used for inventory, lifecycle, configuration, and management endpoints.
Keep ACLs minimal: only grant the roles needed for the tools you actually enable.
SSH batch access to the Proxmox host
Required for pct exec, batch SSH diagnostics, and container-level Docker inspection tools.
This is still necessary because Proxmox API coverage does not replace host-side pct and SSH-based diagnostics.

More detail: docs/PERMISSIONS.md

Destructive confirmations

Operations marked destructive do not execute unless the caller sends confirm=true.

Examples:

VM/container stop, shutdown, reboot, suspend, delete, migrate, snapshot rollback
storage/network/firewall/access writes that can alter cluster state
advanced remote execution such as pve_exec_in_container

The server returns a structured CONFIRMATION_REQUIRED error when confirmation is missing. This behavior is unchanged and reinforced.

Access tiers

read-only
Inventory, status, logs, metrics, and non-mutating diagnostics.
read-execute
Read-only plus selected execution/lifecycle actions.
full
Create, update, delete, migrate, restore, and admin-level operations.

PVE_MODULE_MODE=core hides advanced tools without renaming or removing canonical tool IDs from the codebase.

Runtime configuration

Environment variables

Required:

PROXMOX_HOST
PROXMOX_USER
PROXMOX_REALM
PROXMOX_TOKEN_NAME
PROXMOX_TOKEN_SECRET
PROXMOX_SSH_HOST
PROXMOX_SSH_USER
PROXMOX_SSH_KEY_PATH

Optional:

PROXMOX_PORT default 8006
PROXMOX_SSH_PORT default 22
PROXMOX_ALLOW_INSECURE_TLS default false
PVE_ACCESS_TIER=read-only|read-execute|full
PVE_MODULE_MODE=core|advanced
PVE_CATEGORIES
PVE_TOOL_BLACKLIST
PVE_TOOL_WHITELIST

HTTP transport:

MCP_TRANSPORT=stdio|http
MCP_HOST default 0.0.0.0
MCP_PORT default 3000
MCP_ALLOWED_HOSTS
MCP_ALLOWED_ORIGINS
MCP_RATE_LIMIT_WINDOW_MS
MCP_RATE_LIMIT_MAX
MCP_MAX_BODY_SIZE_BYTES
MCP_HEADERS_TIMEOUT_MS
MCP_REQUEST_TIMEOUT_MS
MCP_KEEPALIVE_TIMEOUT_MS
MCP_MAX_HEADERS_COUNT

Local config file

Setup writes .nandi-proxmox-mcp/config.json and .vscode/mcp.json.

The config loader now rejects:

empty or malformed config paths
oversized config files
control characters in config paths

Quick start

Guided setup:

npx nandi-proxmox-mcp setup
npx nandi-proxmox-mcp doctor --check mcp-config,nodes,vms,cts,node-status,remote-op

Direct run with environment variables:

$env:PROXMOX_HOST="pve.local"
$env:PROXMOX_PORT="8006"
$env:PROXMOX_USER="svc_mcp"
$env:PROXMOX_REALM="pve"
$env:PROXMOX_TOKEN_NAME="nandi-mcp"
$env:PROXMOX_TOKEN_SECRET="<SECRET>"
$env:PROXMOX_SSH_HOST="pve.local"
$env:PROXMOX_SSH_USER="root"
$env:PROXMOX_SSH_KEY_PATH="$env:USERPROFILE\.ssh\id_ed25519"

npx nandi-proxmox-mcp run

Security Model & Residual Risk

This MCP server operates real Proxmox infrastructure and is not a sandboxed environment.

Trust Assumptions

The server is deployed in a trusted environment
Only authorized operators can access it
Network exposure is controlled (not publicly exposed)
Credentials are securely managed

Residual Risks

The following risks are inherent to the system design:

Privileged Operations

Full access tier and container execution capabilities can perform destructive or system-level actions.

SSH Execution Boundary

Remote command execution relies on SSH and inherits the security posture of the target system.

Optional Insecure TLS Mode

When enabled (PROXMOX_ALLOW_INSECURE_TLS=true), TLS certificate validation is bypassed and may expose connections to MITM attacks. Intended for lab use only.

External Dependency Synchronization

Package distribution and listing visibility depend on npm, MCP Registry, and marketplace propagation timing.

Security Responsibilities

Users are responsible for:

Restricting access to trusted operators only
Using least-privilege API tokens and SSH keys
Avoiding insecure TLS in production environments
Properly securing the underlying infrastructure

Safety Controls Implemented

Access tiers (read-only, read-execute, full)
Confirmation required for destructive operations
Input validation and command hardening
Rate limiting and request validation

HTTP hardening

When MCP_TRANSPORT=http is enabled, the server now applies:

host allowlist enforcement, including wildcard-bind protection
origin validation for requests that send an Origin header
explicit body-size limits and sanitized 413 responses
rate limiting on /mcp
request/header/keep-alive timeouts
X-Content-Type-Options: nosniff
Cache-Control: no-store
sanitized error payloads without stack traces

Health/readiness endpoints:

GET /health
GET /ready
POST /mcp

SSH and command-execution hardening

Functionality is unchanged, but the execution path is stricter:

local command execution still uses spawn(..., { shell: false })
SSH host/user values cannot smuggle CLI options
SSH uses BatchMode, IdentitiesOnly, public-key auth, and explicit connection liveness controls
output buffers are capped to prevent unbounded memory growth
dockerLogsInContainer now validates and shell-escapes container names instead of interpolating raw user input
arbitrary container command execution remains available only through the already-destructive pve_exec_in_container flow with confirmation required

Security posture

Mitigations in the repo:

pinned direct dependency versions and npm overrides for critical transitive packages
verifiable package metadata and repository links for npm/package scanners
descriptor/version sync validation for npm, registry, and marketplace artifacts
redaction of token/header/password-like values in logs
no stack traces or secrets returned to clients
CI gates for lint, typecheck, build, tests, metadata validation, descriptor sync, npm pack --dry-run, and audit

Threat model and residual risks: docs/THREAT_MODEL.md

Publish flow

Release order is strict:

npm run lint
npm run typecheck
npm run build
npm test
npm audit --include=dev --audit-level=moderate
npm ls express
npm ls path-to-regexp
npm pack --dry-run
npm pack
npm whoami
npm publish --access public
npm view nandi-proxmox-mcp version
mcp-publisher validate .mcp/server.json
mcp-publisher publish .mcp/server.json

The tag-based release.yml now publishes npm first and only then publishes the MCP Registry descriptor, preventing npm/registry drift on the same version.

Manual fallback and troubleshooting: docs/RELEASE.md

Development

npm ci
npm run lint
npm run typecheck
npm run build
npm test
npm run validate:release
npm pack --dry-run

Documentation Maintenance Policy

This repository enforces a pre-commit documentation sync gate.

Before closing a change, fix, or refactor, evaluate whether README.md, AGENTS.md, and CONTRIBUTING.md must be updated.
If a document is relevant to the behavioral or process impact, it must be updated in the same change set.
If no update is needed, an explicit no-doc-change justification is required.
A task is not considered ready-to-commit until this gate is satisfied.

Docs

Registry and marketplace

npm: https://www.npmjs.com/package/nandi-proxmox-mcp
MCP Registry: https://registry.modelcontextprotocol.io/
MCP Marketplace listing: https://mcp-marketplace.io/server/io-github-nandi-services-nandi-proxmox-mcp

License

MIT. See LICENSE.

proxmox-mcp