Skip to content

Instantly share code, notes, and snippets.

@jmanhype

jmanhype/PROXMOX_MCP_SETUP_GUIDE.md

Created October 10, 2025 00:56
Show Gist options
  • Save jmanhype/d508dafa5bd7fe9d1766a19bf1e1b712 to your computer and use it in GitHub Desktop.
Save jmanhype/d508dafa5bd7fe9d1766a19bf1e1b712 to your computer and use it in GitHub Desktop.
Download ZIP
Proxmox MCP Server Setup Guide for Claude Code - 119 Tools for Infrastructure Management
Raw
PROXMOX_MCP_SETUP_GUIDE.md

Proxmox MCP Server Setup Guide for Claude Code

Complete guide for integrating Proxmox MCP Enhanced with Claude Code CLI to manage Proxmox infrastructure.

Overview

Successfully integrated Proxmox MCP Enhanced v1.0.0 with Claude Code, providing 119 specialized tools for managing Proxmox VE infrastructure including VMs, containers, storage, networking, and more.

Problem Summary

Initially faced issues loading the Proxmox MCP server in Claude Code:

  • ✗ Project .mcp.json files require UI approval in Claude Code
  • ✗ proxmox-mcp command wrapper had initialization issues
  • ✗ Claude Desktop config (claude_desktop_config.json) doesn't apply to Claude Code CLI

Solution: Add to User-Level Claude Code Config

Step 1: Install Proxmox MCP Enhanced

# Clone the repository
git clone https://github.com/jmanhype/proxmox-mcp-enhanced.git
cd proxmox-mcp-enhanced

# Install in development mode
pip install -e .

# Verify installation
pip show proxmox-mcp-enhanced

Step 2: Add Server to Claude Code

Use the Claude Code CLI to add the server with proper configuration:

# Add the server (basic)
claude mcp add -s user proxmox python -m proxmox_mcp.server

Step 3: Add Environment Variables

The claude mcp add command doesn't support environment variables directly, so we need to edit the config file:

# Edit ~/.claude.json and add environment variables to the proxmox server section

Or use this Python script to automate it:

import json

# Read Claude Code config
with open('/Users/YOUR_USERNAME/.claude.json', 'r') as f:
    config = json.load(f)

# Update proxmox server with environment variables
if 'mcpServers' in config and 'proxmox' in config['mcpServers']:
    config['mcpServers']['proxmox']['command'] = 'python'
    config['mcpServers']['proxmox']['args'] = ['-m', 'proxmox_mcp.server']
    config['mcpServers']['proxmox']['env'] = {
        "PROXMOX_HOST": "YOUR_PROXMOX_IP",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "YOUR_TOKEN_NAME",
        "PROXMOX_TOKEN_VALUE": "YOUR_TOKEN_VALUE",
        "PROXMOX_VERIFY_SSL": "false"  # Set to "true" if using valid SSL cert
    }

    # Save config
    with open('/Users/YOUR_USERNAME/.claude.json', 'w') as f:
        json.dump(config, f, indent=2)

    print("✓ Proxmox MCP server configured successfully")

Step 4: Restart Claude Code

After configuration changes:

# Restart Claude Code completely
# The server will auto-load on next startup

Step 5: Verify Installation

# List all MCP servers
claude mcp list

# Look for:
# proxmox: python -m proxmox_mcp.server - ✓ Connected

Configuration File Structure

Final configuration in ~/.claude.json:

{
  "mcpServers": {
    "proxmox": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"],
      "env": {
        "PROXMOX_HOST": "192.168.1.123",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "mcp-server",
        "PROXMOX_TOKEN_VALUE": "your-token-here",
        "PROXMOX_VERIFY_SSL": "false"
      }
    }
  }
}

Setting Up Proxmox API Token

Create API Token in Proxmox

  1. Log into Proxmox web interface
  2. Navigate to Datacenter → Permissions → API Tokens
  3. Click Add
  4. Set:
    • User: root@pam
    • Token ID: mcp-server (or your choice)
    • Privilege Separation: Uncheck (for full access)
  5. Copy the generated token value (only shown once!)

Test API Connection

curl -k -s -H "Authorization: PVEAPIToken=root@pam!mcp-server=YOUR_TOKEN" \
  https://YOUR_PROXMOX_IP:8006/api2/json/version

Expected output:

{
  "data": {
    "version": "8.4.1",
    "release": "8.4",
    "repoid": "..."
  }
}

Available Tools (119 Total)

VM Management (9 tools)

  • vm_list - List all VMs with status
  • vm_create - Create new VM
  • vm_start - Start VM
  • vm_stop - Stop VM
  • vm_restart - Restart VM
  • vm_suspend - Suspend VM to RAM
  • vm_resume - Resume suspended VM
  • vm_clone - Clone VM
  • vm_delete - Delete VM

Container Management (9 tools)

  • container_list - List all LXC containers
  • container_create - Create new container
  • container_start - Start container
  • container_stop - Stop container
  • container_restart - Restart container
  • container_suspend - Suspend container
  • container_resume - Resume container
  • container_migrate - Migrate container
  • container_delete - Delete container

SSH/Exec Tools (4 tools)

  • container_exec - Execute command in container via SSH
  • vm_exec - Execute command in VM (requires qemu-guest-agent)
  • container_push_file - Upload file to container
  • container_pull_file - Download file from container

Storage Management (10 tools)

  • storage_list - List all storage
  • storage_create - Create storage
  • storage_update - Update storage config
  • storage_delete - Delete storage
  • storage_content_list - List storage content
  • storage_upload - Upload to storage
  • storage_download - Download from storage
  • And more...

Additional Categories

  • Cluster Management (8 tools)
  • Monitoring (2 tools)
  • Backup & Recovery (8 tools)
  • Networking (6 tools)
  • High Availability (6 tools)
  • Firewall (5 tools)
  • User Management (3 tools)
  • Templates (4 tools)
  • Migration (3 tools)
  • Snapshots (4 tools)
  • Replication (3 tools)
  • Ceph Storage (5 tools)
  • ZFS Storage (4 tools)
  • SDN/VXLAN (4 tools)
  • Automation (3 tools)
  • Reporting (3 tools)
  • ISO Management (4 tools)

Usage Examples

List All Containers

Ask Claude Code:

"List all my Proxmox containers with their status"

Claude will use the container_list tool automatically.

Execute Command in Container

Ask Claude Code:

"Run 'df -h' in container CT 103"

Claude will use the container_exec tool.

Increase Container CPU Allocation

Ask Claude Code:

"Increase CT 103 CPU cores from 1 to 4"

Claude will:

  1. Stop the container (if running)
  2. Update CPU configuration
  3. Start the container

Create New Container

Ask Claude Code:

"Create a new Ubuntu 22.04 container with 2 CPUs and 2GB RAM"

Troubleshooting

Server Not Connecting

Check the MCP server status:

claude mcp list

Look for ✓ Connected next to proxmox.

Test Server Manually

export PROXMOX_HOST="192.168.1.123"
export PROXMOX_USER="root@pam"
export PROXMOX_TOKEN_NAME="mcp-server"
export PROXMOX_TOKEN_VALUE="your-token"
export PROXMOX_VERIFY_SSL="false"

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | python -m proxmox_mcp.server

Should output:

Starting Proxmox MCP Enhanced Server v1.0.0
Registered tools: 119
{"jsonrpc":"2.0","id":1,"result":{...}}

Environment Variables Not Working

Verify they're set in the config:

grep -A 10 '"proxmox"' ~/.claude.json

Permission Errors

Ensure API token has proper permissions:

  • Token should be created for root@pam
  • Privilege Separation should be disabled for full access
  • Or assign specific PVE permissions to the token

Key Differences: Claude Desktop vs Claude Code

Feature Claude Desktop Claude Code (CLI)
Config File ~/Library/Application Support/Claude/claude_desktop_config.json ~/.claude.json
Project MCP .mcp.json requires UI approval .mcp.json requires UI approval
Add Server Command Manual JSON editing claude mcp add command
Scope Global only Local, User, or Project
Auto-load Yes Yes (user/local scope)

Why python -m proxmox_mcp.server Instead of proxmox-mcp

The proxmox-mcp command wrapper had initialization issues:

  • ✗ Timed out during MCP handshake
  • ✗ Didn't properly initialize async event loop
  • ✓ python -m proxmox_mcp.server works reliably

Security Considerations

  1. SSL Verification: Set PROXMOX_VERIFY_SSL=true if using valid SSL certificates
  2. API Token Scope: Consider creating a dedicated token with limited permissions
  3. Token Storage: The token is stored in plain text in ~/.claude.json
  4. Network Access: Ensure Proxmox API (port 8006) is accessible from Claude Code

Resources

Credits

  • Server: Proxmox MCP Enhanced v1.0.0
  • Developer: jmanhype
  • Protocol: Model Context Protocol (MCP)
  • AI Assistant: Claude Code by Anthropic

Status: ✅ WORKING - 119 tools successfully integrated with Claude Code

Last Updated: 2025-10-09

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment