Proxmox VE 管理 MCP 服务器

MCP Server for Proxmox VE

A Model Context Protocol (MCP) server for Proxmox Virtual Environment that enables AI assistants to manage virtual machines, containers, nodes, and resources through natural language interactions.

🚀 Features

Core Proxmox Management

• Node Management: List and monitor Proxmox cluster nodes
• VM Operations: Start, stop, and monitor virtual machines
• Container Management: Manage LXC containers
• Status Monitoring: Real-time status information for nodes, VMs, and containers

🆕 Full Container Provisioning (v0.2.0)

• Automated Provisioning: Create containers with full infrastructure automation
• Netbox IPAM Integration: Automatic IP and VM registration
• NPM Reverse Proxy: Automatic proxy host creation with SSL
• DNS Registration: Automatic AdGuard Home DNS entries
• Monitoring Setup: Automatic node_exporter and promtail installation
• Backup Configuration: Automatic Proxmox backup scheduling
• Template Stacks: Pre-configured templates (media, dev, monitoring)
• CTID Auto-Assignment: Intelligent CTID assignment by function

Infrastructure

• Secure Authentication: Support for both password and API token authentication
• Multi-Node Support: Works with single nodes or full Proxmox clusters
• Natural Language: Deploy infrastructure by talking to AI

📋 Prerequisites

• Node.js 18.0.0 or higher
• Proxmox VE 7.0+ with API access
• Valid Proxmox credentials (username/password or API token)

🛠️ Installation

From Source

git clone https://github.com/heybearc/mcp-server-proxmox.git
cd mcp-server-proxmox
npm install
npm run build

From NPM (Coming Soon)

npm install -g mcp-server-proxmox

⚙️ Configuration

Environment Variables

Create a .env file or set the following environment variables:

# Proxmox Server Configuration
PROXMOX_HOST=your-proxmox-host.com
PROXMOX_PORT=8006
PROXMOX_USERNAME=root
PROXMOX_REALM=pam

# Authentication Method 1: Password
PROXMOX_PASSWORD=your-password

# Authentication Method 2: API Token (Recommended)
PROXMOX_TOKEN=your-api-token
PROXMOX_TOKEN_NAME=your-token-name

# SSL Configuration
PROXMOX_VERIFY_SSL=true

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/path/to/mcp-server-proxmox/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-host.com",
        "PROXMOX_USERNAME": "root",
        "PROXMOX_TOKEN": "your-api-token",
        "PROXMOX_TOKEN_NAME": "your-token-name"
      }
    }
  }
}

Other MCP Clients

Refer to your MCP client's documentation for server configuration.

🔧 Available Tools

Basic Operations

🆕 Provisioning Tools (v0.2.0)

💡 Usage Examples

With AI Assistant

Basic Operations:

"Show me all VMs on my Proxmox cluster"
"Start VM 100 on node pve1"
"What's the status of my Proxmox nodes?"
"List all containers on node pve2"

🆕 Provisioning (v0.2.0):

"Create a new media server container with 4GB RAM at 10.92.3.15"
"Deploy a Scrypted NVR container with domain scrypted.cloudigan.net"
"Provision a development environment at 10.92.3.50"
"What's the next available CTID for utility containers?"

Natural Language Examples:

• "I need a new container for Plex with 8GB RAM and SSL enabled"
• "Create a monitoring stack at 10.92.3.60 with Grafana access"
• "Deploy a dev environment with 2 cores and 32GB disk"

Direct API Usage

# Start the server
npm start

# The server communicates via stdio using MCP protocol

🔐 Security

API Token Setup (Recommended)

1. Log into Proxmox web interface
2. Go to Datacenter → Permissions → API Tokens
3. Create a new token with appropriate permissions
4. Use the token in your configuration

Required Permissions

• VM.Audit - View VM information
• VM.PowerMgmt - Start/stop VMs
• Sys.Audit - View node information
• Datastore.Audit - View storage information

🧪 Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• Model Context Protocol
• MCP TypeScript SDK
• Proxmox VE API Documentation

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• 📧 Contact