ProxmoxMCP-Plus

Open-source MCP server for Proxmox VE automation.
This repository provides a secure control plane for VM and container lifecycle operations, plus an OpenAPI bridge for integrations.

Documentation strategy: this README is the stable entrypoint, while detailed runbooks and references live in Wiki. This keeps onboarding fast while preserving operational depth in one canonical location.

Quick Start | Security | API Reference | Troubleshooting

ProxmoxMCP-Plus is designed for teams that need:

• Reliable MCP-native automation for Proxmox clusters
• Operationally safe execution paths with policy controls
• Integration flexibility across MCP clients and HTTP/OpenAPI consumers
• A documentation model where README stays concise and Wiki carries deep guidance

This project builds on canvrno/ProxmoxMCP, and extends it for enterprise-oriented deployment and operations.

Target audience:

• Platform engineering teams operating Proxmox at scale
• AI platform teams exposing virtualization controls to assistant workflows
• Infrastructure teams requiring auditable and policy-aware automation

High-level architecture:

• MCP Server: stdio MCP interface for assistants and MCP clients
• Tooling Layer: VM, container, storage, snapshot, backup, and cluster operations
• Security Layer: token auth, command policy, and scoped execution controls
• Observability Layer: logging and health visibility
• OpenAPI Bridge: HTTP exposure for external platforms

Capability groups:

Full endpoint and tool details are maintained in Wiki: API & Tool Reference.

Operational boundaries:

• ProxmoxMCP-Plus orchestrates Proxmox operations; it does not replace cluster-level backup/HA design.
• Security controls in this service must be paired with network segmentation and Proxmox RBAC.
• OpenAPI exposure is intended for controlled environments, not unauthenticated public access.

Prerequisites:

• Python 3.9+
• uv package manager
• Proxmox API token with required permissions

Minimal setup:

git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git
cd ProxmoxMCP-Plus
uv venv
uv pip install -e ".[dev]"

Create runtime config:

cp proxmox-config/config.example.json proxmox-config/config.json

Set required fields in proxmox-config/config.json:

• proxmox.host
• auth.user
• auth.token_name
• auth.token_value

Run MCP server:

python main.py

Optional OpenAPI mode:

docker compose up -d

Health endpoint:

curl -f http://localhost:8811/health

For production deployment details, use Operator Guide.

Validation path for first run:

1. Start server and verify no startup auth errors.
2. Call a read-only tool such as node or VM listing.
3. Validate /health when OpenAPI mode is enabled.
4. Proceed to write operations only after policy and RBAC validation.

• Claude Desktop: Integrations Guide
• Cline: Integrations Guide
• Open WebUI: Integrations Guide
• OpenAPI / Swagger: http://<host>:8811/docs and API & Tool Reference

Integration expectations:

• Keep client-specific connection settings outside committed source files.
• Use environment-specific API keys when exposing OpenAPI.
• Test with read-only operations before enabling lifecycle mutation workflows.

Security posture summary:

• API-token based Proxmox authentication
• Environment-aware controls (dev_mode for development-only relaxation)
• Command execution policy and allow/deny constraints
• Operational logging and health visibility

Security baseline, hardening checklist, and threat boundaries are documented in Security Guide.

Minimum production controls:

• Enforce security.dev_mode=false
• Restrict ingress to trusted networks or VPN paths
• Terminate TLS at an approved reverse proxy
• Rotate API credentials regularly and monitor denied operations

Developer workflow:

pytest
ruff .
mypy .
black .

Contribution standards, local setup, and validation expectations are maintained in Developer Guide.

Pull request quality bar:

• Behavior changes are covered by tests
• Type and lint checks pass in CI
• Documentation updates are included when interfaces or operations change

Support channels:

• Bug reports and feature requests: GitHub Issues
• Operational incidents and known fixes: Troubleshooting

FAQ shortcuts:

• How do I deploy to production? See Operator Guide.
• Where are all tools/endpoints listed? See API & Tool Reference.
• How do I configure secure command execution? See Security Guide.

Escalation guidance:

• For security-sensitive incidents, collect logs and request context before remediation.
• For breaking behavior after upgrade, compare against Release & Upgrade Notes.

GitHub Wiki is the source of truth for detailed documentation.
If Wiki is not enabled yet, enable it in repository settings first, then publish the seed pages from docs/wiki/.

Local seed pages for Wiki bootstrap are available in docs/wiki/.

README remains intentionally concise and stable.
Detailed operational guidance, examples, and runbooks live in Wiki.

The following entry points are treated as stable documentation interfaces:

• Quick Start: repository bootstrap and first-run verification
• Security: baseline controls and hardening navigation
• API Reference: tool and endpoint behavior index
• Troubleshooting: incident diagnosis and recovery guidance

When documentation changes:

1. Update the relevant Wiki page first.
2. Keep README links stable unless there is a structural migration.
3. Record version-impacting documentation updates in Release & Upgrade Notes.

MIT License