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

Fastest repeatable setup for an existing Proxmox server:

npx nandi-proxmox-mcp setup `
  --proxmox-host <PROXMOX_HOST> `
  --proxmox-user <PROXMOX_USER> `
  --token-name <TOKEN_NAME> `
  --token-secret "<TOKEN_SECRET>" `
  --ssh-key-path "$env:USERPROFILE\\.ssh\\id_ed25519" `
  --skip-connectivity

Fast doctor against a real container:

npx nandi-proxmox-mcp doctor `
  --check mcp-config,nodes,vms,cts,node-status,remote-op `
  --ctid <CTID>

One-command Windows install:

powershell -ExecutionPolicy Bypass -File .\scripts\setup-win.ps1 `
  -ProxmoxHost <PROXMOX_HOST> `
  -ProxmoxUser <PROXMOX_USER> `
  -TokenName <TOKEN_NAME> `
  -TokenSecret "<TOKEN_SECRET>" `
  -DoctorCtid <CTID>

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.

Install from MCP marketplace / plugin marketplace

The npm package is already public, but marketplace discovery has an additional submission process.

• MCP marketplace (@mcp in VS Code): submit server metadata + mcp-manifest.json + npm package reference.
• Codex/VS Code recommended servers: publish the corresponding Agent Plugin in the configured plugin marketplace.

Submission metadata and assets are prepared in:

• marketplace/listing.md
• marketplace/security.md
• marketplace/icon.png
• marketplace/screenshot-setup.png
• marketplace/mcp-registry/server.json
• marketplace/agent-plugin-marketplace/.github/plugin/marketplace.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
• Release Notes v0.1.4
• 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.