nandi-proxmox-mcp

Open source MCP Server for Proxmox, powered by NANDI Services.

nandi-proxmox-mcp lets users connect to their own Proxmox server and operate nodes, VMs, and CT/LXC securely via MCP tools in VS Code.

Important: API token ownership

The Proxmox API token is not delivered by npm, VS Code, or this MCP package. Each user must create a token in their own Proxmox environment with minimum ACL permissions.

5-minute Quickstart (Windows)

1. Install Node.js 20+.

2. Run npm install -g nandi-proxmox-mcp.

3. Run nandi-proxmox-mcp setup and complete guided onboarding.

4. Run nandi-proxmox-mcp doctor --check mcp-config,nodes,vms,cts,node-status,remote-op.

5. Open VS Code and confirm MCP server is registered (.vscode/mcp.json).

Alternative direct run:

• npx nandi-proxmox-mcp setup

• npx nandi-proxmox-mcp run

VS Code / Codex plug-and-play paths

• Custom server: use .vscode/mcp.json (root servers format).

• Manifest install: use mcp-manifest.json.

• User-level config template: templates/vscode.user.mcp.template.json.

MCP tools included

• Inventory: listNodes, listVMs, listContainers

• Status: getNodeStatus, getVMStatus, getContainerStatus

• Control: startVM, stopVM, startContainer, stopContainer

• CT operations: execInContainer, dockerPsInContainer, dockerLogsInContainer, runRemoteDiagnostic, sshBatchDiagnostics

Security principles

• No hardcoded host/token secrets in versioned files.

• Local sensitive config generated in .nandi-proxmox-mcp/config.json.

• Templates with placeholders only.

• CI includes secret scanning and dependency scanning.

Docs

• Quickstart

• Windows Installation

• Proxmox Token + ACL Setup

• SSH Setup and Batch Validation

• VS Code MCP Setup

• Marketplace Go-Live

• Security Guide

• Troubleshooting

• FAQ

• CI Secrets Policy

Development

• npm ci

• npm run lint

• npm run typecheck

• npm test

• npm run build

License

MIT. See LICENSE.