io.github.NANDI-Services/nandi-proxmox-mcp
Open-source MCP server for secure Proxmox node, VM, and LXC operations.
Ask AI about io.github.NANDI-Services/nandi-proxmox-mcp
Powered by Claude · Grounded in docs
I know everything about io.github.NANDI-Services/nandi-proxmox-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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. stdiotransport 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
pctand SSH-based diagnostics.
- Required for
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_HOSTPROXMOX_USERPROXMOX_REALMPROXMOX_TOKEN_NAMEPROXMOX_TOKEN_SECRETPROXMOX_SSH_HOSTPROXMOX_SSH_USERPROXMOX_SSH_KEY_PATH
Optional:
PROXMOX_PORTdefault8006PROXMOX_SSH_PORTdefault22PROXMOX_ALLOW_INSECURE_TLSdefaultfalsePVE_ACCESS_TIER=read-only|read-execute|fullPVE_MODULE_MODE=core|advancedPVE_CATEGORIESPVE_TOOL_BLACKLISTPVE_TOOL_WHITELIST
HTTP transport:
MCP_TRANSPORT=stdio|httpMCP_HOSTdefault0.0.0.0MCP_PORTdefault3000MCP_ALLOWED_HOSTSMCP_ALLOWED_ORIGINSMCP_RATE_LIMIT_WINDOW_MSMCP_RATE_LIMIT_MAXMCP_MAX_BODY_SIZE_BYTESMCP_HEADERS_TIMEOUT_MSMCP_REQUEST_TIMEOUT_MSMCP_KEEPALIVE_TIMEOUT_MSMCP_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
Originheader - explicit body-size limits and sanitized
413responses - rate limiting on
/mcp - request/header/keep-alive timeouts
X-Content-Type-Options: nosniffCache-Control: no-store- sanitized error payloads without stack traces
Health/readiness endpoints:
GET /healthGET /readyPOST /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
dockerLogsInContainernow 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_containerflow with confirmation required
Security posture
Mitigations in the repo:
- pinned direct dependency versions and npm
overridesfor 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 lintnpm run typechecknpm run buildnpm testnpm audit --include=dev --audit-level=moderatenpm ls expressnpm ls path-to-regexpnpm pack --dry-runnpm packnpm whoaminpm publish --access publicnpm view nandi-proxmox-mcp versionmcp-publisher validate .mcp/server.jsonmcp-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, orrefactor, evaluate whetherREADME.md,AGENTS.md, andCONTRIBUTING.mdmust 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-changejustification is required. - A task is not considered ready-to-commit until this gate is satisfied.
Docs
- docs/QUICKSTART.md
- docs/PERMISSIONS.md
- docs/SECURITY.md
- docs/THREAT_MODEL.md
- docs/RELEASE.md
- docs/TROUBLESHOOTING.md
- docs/TOOLS.md
- docs/MARKETPLACE_GO_LIVE.md
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.
