pxcloud-mcp

Model Context Protocol (MCP) server for PXCloud — enables AI assistants to manage Proxmox VE and VMware vSphere infrastructure through natural language.

What is this?

pxcloud-mcp is an MCP server that bridges AI assistants (OpenClaw, Windsurf, Cursor, Claude Desktop) with PXCloud — a multi-platform virtualization management system.

Zero-configuration tool discovery: The server automatically fetches your PXCloud API schema and exposes all endpoints as MCP tools. No manual tool definitions needed.

Features

• Auto-discovery: Fetches OpenAPI spec on startup, automatically exposes all API endpoints as MCP tools
• AI-native: Rich AI hints embedded in API descriptions guide LLMs to use tools correctly
• Safety-first: Built-in guards for destructive operations (DELETE, power actions, migrations)
• Secure: JWT authentication, TLS support, configurable privilege scopes
• Workflow prompts: Built-in prompt templates for operator, troubleshooting, batch, and monitoring tasks

Installation

npm install -g pxcloud-mcp

Or use with npx (no installation):

npx pxcloud-mcp

Quick Start

1. Configure your MCP client

Add to your MCP client configuration (Windsurf, Cursor, Claude Desktop, etc.):

{
  "mcpServers": {
    "pxcloud": {
      "command": "npx",
      "args": ["-y", "pxcloud-mcp"],
      "env": {
        "PXCLOUD_URL": "https://your-pxcloud-server:8443",
        "PXCLOUD_USER": "admin",
        "PXCLOUD_PASS": "your-password"
      }
    }
  }
}

2. Start using

Ask your AI assistant:

• "List all running VMs"
• "Create a console share link for VM abc123:pve1:100"
• "Migrate VM abc123:pve1:100 to node pve2 with storage local-ssd"
• "Show me nodes with high CPU usage"

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PXCLOUD_URL | Yes | — | PXCloud server URL (e.g., https://192.168.1.10:8443) | | PXCLOUD_USER | Yes* | — | Login username | | PXCLOUD_PASS | Yes* | — | Login password | | PXCLOUD_TOKEN | Alternative | — | Pre-authenticated JWT token (bypasses login) | | PXCLOUD_TLS_VERIFY | No | false | Strict TLS verification (disable for self-signed certs) | | PXCLOUD_ALLOW_DELETE | No | true | Expose DELETE endpoints | | PXCLOUD_TOOLS | No | all | Comma-separated OpenAPI tags to expose (e.g., VMs,Clusters,Nodes) |

*Required unless using PXCLOUD_TOKEN

Example: Restrict to specific modules

{
  "mcpServers": {
    "pxcloud": {
      "command": "npx",
      "args": ["-y", "pxcloud-mcp"],
      "env": {
        "PXCLOUD_URL": "https://pxcloud.internal:8443",
        "PXCLOUD_TOKEN": "eyJhbGciOiJIUzI1NiIs...",
        "PXCLOUD_TOOLS": "VMs,Clusters,Nodes",
        "PXCLOUD_ALLOW_DELETE": "false"
      }
    }
  }
}

How it works

Auto-Discovery Flow

┌─────────────────┐     ┌──────────────┐     ┌──────────────────┐
│   MCP Client    │────▶│  pxcloud-mcp  │────▶│  PXCloud Server  │
│  (AI Assistant) │     │   (this pkg)  │     │   (/api-docs)    │
└─────────────────┘     └──────────────┘     └──────────────────┘
                              │
                              ▼
                       ┌──────────────┐
                       │  Generate    │
                       │  ~140 tools  │
                       │  from spec   │
                       └──────────────┘

1. Startup: MCP server logs into PXCloud
2. Discovery: Fetches /api-docs/openapi.json
3. Generation: Creates MCP tools from OpenAPI operations
4. Runtime: Executes HTTP requests via generic proxy

AI Hints Integration

AI hints embedded in PXCloud API automatically flow to the LLM:

// In PXCloud Rust backend
/// Create a one-time console share link. AI hint: generates token-based URL 
/// for sharing VM console. Requires VM.Console privilege. 
/// expires_in_seconds: 60–604800 (1min–7days).
#[utoipa::path(...)]
pub async fn create_share(...) { ... }

↓ OpenAPI spec

{
  "summary": "Create a one-time console share link. AI hint: generates token-based URL...",
  "description": "..."
}

↓ MCP tool description

LLM sees the full guidance when deciding to use this tool.

Safety Features

Destructive Operation Guard

Operations marked as destructive (DELETE, power-off, migrations) require explicit confirmation:

1. AI attempts operation → intercepted with confirmation_required
2. AI calls pxcloud_confirm_change → user approves via UI
3. AI retries with confirmed: true → operation executes

Error Recovery

Automatic recovery hints based on HTTP status codes:

| Status | Recovery Action | |--------|----------------| | 401 | Token expired, re-login | | 403 | Insufficient privileges | | 404 | Resource not found, verify with list tools | | 409 | State conflict, check current state | | 429 | Rate limited, wait and retry | | 502/503/504 | Gateway/node unavailable, check health |

Console Share Workflow

Create shareable console access links:

// AI calls:
pxcloud_post_api_vms__id__console_share({
  id: "cluster1:pve1:100",
  access_mode: "view_only",      // or "full_control"
  expires_in_seconds: 3600       // 1 hour
})

// Returns:
{
  id: "share-uuid",
  token: "a1b2c3d4e5f6...",
  access_mode: "view_only",
  expires_at: 1699123456
}

Share URL: https://<pxcloud>/console/share/<token>

Users opening the link get instant console access without needing a PXCloud account.

Built-in Prompts

| Prompt | Purpose | |--------|---------| | pxcloud_operator | General operations with safety guidelines | | pxcloud_troubleshoot | Diagnostic methodology | | pxcloud_batch | Batch operations with failure handling | | pxcloud_monitor | Monitoring checklists |

API Coverage

• VMs: Lifecycle, power, migrate, snapshots, backups, firewall
• Nodes: Status, storage, network, hardware, IPMI
• Clusters: Proxmox VE, VMware vSphere
• IPAM: IPv4 pools, subnets, assignment
• Physical Servers: BMC/Redfish hardware info, power control
• Console: VNC, terminal, share links
• Tasks: Async operation tracking
• Infrastructure: Regions, datacenters, cabinets
• Access Control: Users, groups, roles, ACL
• Monitoring: Sensors, business monitors, alerts

Excluded: WebSocket streaming endpoints (/vnc/, /terminal/, /ws) — MCP protocol doesn't support persistent connections.

Development

git clone https://atomgit.com/lierfang/pxcloud-mcp
npm install
npm run dev

Testing with CLI

PXCLOUD_URL=https://localhost:8443 \
PXCLOUD_USER=admin \
PXCLOUD_PASS=admin \
npx tsx src/index.ts

Troubleshooting

"Cannot connect to PXCloud"

• Verify PXCLOUD_URL is reachable from the MCP server host
• For self-signed certificates, ensure PXCLOUD_TLS_VERIFY=false
• Check firewall rules (port 8443/tcp)

"Authentication failed"

• Verify username/password
• Check if account is locked or MFA-enabled
• Try using PXCLOUD_TOKEN instead

"No tools available"

• Verify PXCloud server is running and /api-docs/openapi.json is accessible
• Check PXCLOUD_TOOLS filter isn't too restrictive

Requirements

• Node.js ≥ 18
• PXCloud server ≥ 0.1.0
• MCP client supporting stdio transport

Links

• PXCloud Repository
• MCP Protocol
• Issue Tracker
• npm Package