Proxmox MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to Proxmox VE API for complete virtualization infrastructure management. Compatible with any MCP client including Claude Desktop, Cline, and other MCP-compatible applications.

Features

Virtual Machine & Container Management

• List, create, start, stop, shutdown, reboot VMs and LXC containers
• Get detailed status and resource usage
• Update VM/container configurations
• Delete VMs and containers

Snapshot Management

• Create, list, delete snapshots
• Rollback to previous snapshots
• Snapshot descriptions and metadata

Storage Management

• List available storage locations
• Browse storage content (ISOs, templates, backups, disk images)
• Check storage capacity and usage

Node & Cluster Operations

• List all cluster nodes
• Get node status and resource usage
• View cluster status and quorum
• Network configuration management
• Version information

Task Monitoring

• List running and completed tasks
• Get task status and progress
• View task logs for debugging

User & Access Management

• List users and permissions
• Manage resource pools
• View pool members and assignments

⚠️ Security Notice

IMPORTANT: This server includes enterprise-grade security features. Before deploying, please review:

• 🔒 SECURITY.md - Security policy and best practices
• 📖 SECURITY_IMPLEMENTATION.md - Technical implementation details

Key Security Features:

• ✅ Input validation with Joi schemas (prevents injection attacks)
• ✅ Multi-tier rate limiting (prevents API abuse)
• ✅ Comprehensive audit logging (security monitoring)
• ✅ SSL verification enabled by default (prevents MITM attacks)
• ✅ Confirmation required for destructive operations
• ✅ Error message sanitization (prevents information disclosure)

Production Requirements:

• ✅ Always use API tokens (not passwords)
• ✅ Keep SSL verification enabled (PROXMOX_VERIFY_SSL=true)
• ✅ Never commit .env files or credentials to version control
• ✅ Keep dependencies updated with npm audit

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Proxmox VE 9.x (tested and developed on version 9)
• API access credentials (API token recommended)

Quick Setup

1. Clone the repository:

git clone https://github.com/yourusername/proxmox-mcp-server.git
cd proxmox-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Test the connection (optional):

# Set environment variables
export PROXMOX_HOST=your-proxmox-server.com
export PROXMOX_USERNAME=root
export PROXMOX_REALM=pam
export PROXMOX_TOKEN_ID=your-token-id
export PROXMOX_TOKEN_SECRET=your-token-secret
export PROXMOX_VERIFY_SSL=false

# Run the server
npm run dev

You should see:

Connected to Proxmox VE X.X-X
Proxmox MCP Server running on stdio

Configuration

Creating API Tokens in Proxmox (Recommended)

API tokens provide stateless authentication and are preferred for automation:

1. Log into Proxmox web interface
2. Navigate to Datacenter → Permissions → API Tokens
3. Click Add to create a new token
4. Configure:
   • User: Select your user (e.g., root@pam)
   • Token ID: Give it a name (e.g., mcp-server)
   • Privilege Separation: Uncheck for full permissions
5. Click Add
6. IMPORTANT: Copy the token secret immediately - it won't be shown again!

Benefits of API Tokens:

• No CSRF token required
• Stateless authentication
• Can be revoked without affecting user account
• Separate permissions per token
• No expiration like session tickets

MCP Client Configuration

This server works with any MCP-compatible client. Add it to your client's configuration file:

Claude Desktop

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/absolute/path/to/proxmox-mcp-server/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-server.com",
        "PROXMOX_USERNAME": "root",
        "PROXMOX_REALM": "pam",
        "PROXMOX_TOKEN_ID": "your-token-id",
        "PROXMOX_TOKEN_SECRET": "your-token-secret",
        "PROXMOX_VERIFY_SSL": "false"
      }
    }
  }
}

Cline (VSCode Extension)

Add to .vscode/settings.json in your project:

{
  "cline.mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/absolute/path/to/proxmox-mcp-server/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-server.com",
        "PROXMOX_USERNAME": "root",
        "PROXMOX_REALM": "pam",
        "PROXMOX_TOKEN_ID": "your-token-id",
        "PROXMOX_TOKEN_SECRET": "your-token-secret",
        "PROXMOX_VERIFY_SSL": "false"
      }
    }
  }
}

Other MCP Clients

Follow your client's documentation for MCP server configuration. The pattern is always:

• command: node
• args: Path to dist/index.js
• env: Environment variables listed below

Environment Variables

Required

• PROXMOX_HOST: IP address or hostname of your Proxmox server
• PROXMOX_USERNAME: Proxmox username (usually root)

Authentication (choose one method)

Option A: API Token (Recommended)

• PROXMOX_TOKEN_ID: Your API token ID
• PROXMOX_TOKEN_SECRET: Your API token secret

Option B: Password

• PROXMOX_PASSWORD: Your user password

Optional

• PROXMOX_PORT: API port (default: 8006)
• PROXMOX_REALM: Authentication realm (default: pam)
• PROXMOX_VERIFY_SSL: Verify SSL certificates (default: true)
  • ⚠️ SECURITY: Always use true in production
  • Only set to false for development with self-signed certificates
  • Setting to false makes you vulnerable to man-in-the-middle attacks

Usage Examples

Once configured with your MCP client, you can interact with Proxmox using natural language:

"List all VMs in my Proxmox cluster"
"Show me the status of VM 100 on node pve1"
"Create a snapshot called 'before-update' for VM 101"
"Start VM 102"
"What's the current resource usage on node pve1?"
"List all available storage locations"
"Show me recent tasks"

Available Tools

VM & Container Management

• list_vms - List all virtual machines and containers

  • Optional filters: node, type (qemu/lxc), status

• get_vm_status - Get detailed status of a specific VM/container

  • Parameters: node, vmid, type

• start_vm, stop_vm, shutdown_vm, reboot_vm - Control VM power state

  • Parameters: node, vmid, type

• create_vm - Create a new virtual machine

  • Parameters: node, vmid, name, cores, memory, storage, etc.

• create_container - Create a new LXC container

  • Parameters: node, vmid, ostemplate, hostname, memory, etc.

• delete_vm - Delete a VM or container

  • Parameters: node, vmid, type

• get_vm_config, update_vm_config - Get or update VM configuration

Snapshot Management

• list_snapshots - List all snapshots for a VM/container
• create_snapshot - Create a new snapshot
• delete_snapshot - Delete a snapshot
• rollback_snapshot - Rollback to a previous snapshot

Storage Management

• list_storage - List all storage locations
• get_storage_content - List content in a storage location
  • Filter by content type: iso, vztmpl, backup, images

Node & Cluster

• list_nodes - List all cluster nodes with resource usage
• get_node_status - Get detailed status of a specific node
• get_cluster_status - Get overall cluster status and quorum
• get_version - Get Proxmox VE version information
• get_network_config - Get network configuration for a node

Task Management

• list_tasks - List tasks on a node
• get_task_status - Get status of a specific task
• get_task_log - Get log output of a task

User & Access

• list_users - List all users with permissions
• list_pools, get_pool - List or get details of resource pools

Project Structure

proxmox-mcp-server/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── types/
│   │   └── proxmox.ts        # TypeScript type definitions
│   ├── utils/
│   │   └── proxmox-client.ts # Proxmox API client
│   └── tools/
│       ├── vm-tools.ts       # VM management tools
│       ├── snapshot-tools.ts # Snapshot tools
│       ├── storage-tools.ts  # Storage tools
│       ├── node-tools.ts     # Node/cluster tools
│       ├── task-tools.ts     # Task monitoring tools
│       └── user-tools.ts     # User/access tools
├── dist/                     # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Development

Build Commands

# Build once
npm run build

# Watch mode (rebuild on changes)
npm run watch

# Run directly (builds first)
npm run dev

Adding New Tools

1. Create or modify tool files in src/tools/
2. Follow the existing pattern for tool definitions
3. Register tools in src/index.ts
4. Rebuild with npm run build

Troubleshooting

Connection Issues

Problem: "Failed to connect to Proxmox API"

• Verify PROXMOX_HOST is correct and accessible
• Check firewall allows port 8006
• Ensure Proxmox API is running

Problem: "Authentication failed"

• Verify credentials are correct
• For API tokens: check token ID and secret match exactly
• Check realm is correct (usually 'pam' or 'pve')
• Ensure token/user has required permissions

SSL Certificate Issues

Problem: "SSL certificate verification failed"

• Set PROXMOX_VERIFY_SSL=false for self-signed certificates
• Or install proper SSL certificates on Proxmox
• In production, use valid certificates and set PROXMOX_VERIFY_SSL=true

Permission Issues

Problem: "Permission denied" errors

• Verify user/token has required permissions
• Check role assignments in Proxmox
• For tokens: ensure "Privilege Separation" is disabled if needed

Security Best Practices

⚠️ IMPORTANT: Review SECURITY.md and SECURITY_IMPLEMENTATION.md before production deployment!

Authentication & Credentials

1. Use API Tokens instead of passwords for automation
   • Stateless authentication
   • Can be scoped and revoked independently
   • No session management required
2. Set appropriate permissions - create tokens with minimal required privileges
3. Never commit credentials to version control
   • Use .env files (already in .gitignore)
   • Copy .env.example to .env and fill in your values
4. Rotate tokens regularly (at least every 90 days)
5. Use separate tokens for different applications/purposes

Network & Transport Security

6. Enable SSL verification in production (PROXMOX_VERIFY_SSL=true)
   • Default is now true for security
   • Only disable for development with self-signed certificates
   • Disabling SSL verification makes you vulnerable to MITM attacks
7. Restrict network access - use firewalls and VPNs
8. Don't expose Proxmox API to the public internet

Monitoring & Auditing

9. Monitor API usage through Proxmox task logs
10. Enable audit logging for all operations
11. Review logs regularly for suspicious activity
12. Set up alerts for failed authentication attempts

Maintenance

13. Keep dependencies updated - run npm audit regularly
14. Review security advisories - check GitHub Security tab
15. Test security updates before deploying to production
16. Have an incident response plan ready

Additional Resources

• 🔒 SECURITY.md - Security policy and vulnerability reporting
• 📖 SECURITY_IMPLEMENTATION.md - Technical implementation details
• 📖 Proxmox Security Best Practices

API Reference

For detailed Proxmox API documentation:

• https://pve.proxmox.com/wiki/Proxmox_VE_API
• https://pve.proxmox.com/pve-docs/api-viewer/

Contributing

Contributions are welcome! Please ensure:

• Code follows TypeScript best practices
• All tools have proper input validation
• Error handling is comprehensive
• Documentation is updated

License

MIT

Support

For issues related to:

• This MCP server: Open an issue in this repository
• Proxmox VE: Visit https://forum.proxmox.com/
• MCP Protocol: Visit https://modelcontextprotocol.io/

Security

This project has undergone a comprehensive security audit and implementation by Bob Shell AI Assistant (August 2026).

Security Features Implemented

• ✅ Input validation with Joi schemas
• ✅ Multi-tier rate limiting (4 levels)
• ✅ Comprehensive audit logging with Winston
• ✅ Error message sanitization
• ✅ SSL verification enabled by default
• ✅ Confirmation required for destructive operations
• ✅ Request timeouts (30 seconds)
• ✅ Secure credential management

Security Documentation

• 🔒 SECURITY.md - Security policy and best practices
• 📖 SECURITY_IMPLEMENTATION.md - Implementation details

Security Review Credits: Bob Shell AI Assistant - Comprehensive security audit and implementation (August 2026)

Changelog

Version 1.0.0

• Initial release
• Complete VM/Container management
• Snapshot operations
• Storage management
• Node and cluster monitoring
• Task tracking
• User and pool management
• API token and password authentication support
• Security enhancements: Input validation, rate limiting, audit logging, error sanitization