MCP 服务器

nandi-proxmox-mcp

An open-source MCP server for managing Proxmox environments, including nodes, virtual machines, and containers. It enables users to perform inventory checks, status monitoring, and control operations directly through MCP-compatible tools.

README

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)

Install Node.js 20+.
Run npm install -g nandi-proxmox-mcp.
Run nandi-proxmox-mcp setup and complete guided onboarding.
Run nandi-proxmox-mcp doctor --check mcp-config,nodes,vms,cts,node-status,remote-op.
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