Related MCP Server Resources

Explore more AI models, providers, and integration options:

  • Explore AI Models
  • Explore AI Providers
  • Explore MCP Servers
  • LangDB Pricing
  • Documentation
  • AI Industry Blog
  • MCP SSH Server
  • Xano MCP Server
  • ERPNext MCP Server
  • Image Processor MCP Server
  • Chrome Debug MCP Server
Back to MCP Servers
Proxmox MCP Server

Proxmox MCP Server

Public
canvrno/ProxmoxMCP

Python-based Model Context Protocol server enabling secure, type-safe management of Proxmox hypervisors with API token authentication, VM and node control, console command execution, and customizable logging.

python
0 tools
May 30, 2025
Updated Jun 4, 2025

Supercharge Your AI with Proxmox MCP Server

MCP Server

Unlock the full potential of Proxmox MCP Server through LangDB's AI Gateway. Get enterprise-grade security, analytics, and seamless integration with zero configuration.

Unified API Access
Complete Tracing
Instant Setup
Get Started Now

Free tier available • No credit card required

Instant Setup
99.9% Uptime
10,000+Monthly Requests

🚀 Proxmox Manager - Proxmox MCP Server

ProxmoxMCP

A Python-based Model Context Protocol (MCP) server for interacting with Proxmox hypervisors, providing a clean interface for managing nodes, VMs, and containers.

🏗️ Built With

  • Cline - Autonomous coding agent - Go faster with Cline.
  • Proxmoxer - Python wrapper for Proxmox API
  • MCP SDK - Model Context Protocol SDK
  • Pydantic - Data validation using Python type annotations

✨ Features

  • 🤖 Full integration with Cline
  • 🛠️ Built with the official MCP SDK
  • 🔒 Secure token-based authentication with Proxmox
  • 🖥️ Tools for managing nodes and VMs
  • 💻 VM console command execution
  • 📝 Configurable logging system
  • ✅ Type-safe implementation with Pydantic
  • 🎨 Rich output formatting with customizable themes

https://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b

📦 Installation

Prerequisites

  • UV package manager (recommended)
  • Python 3.10 or higher
  • Git
  • Access to a Proxmox server with API token credentials

Before starting, ensure you have:

  • Proxmox server hostname or IP
  • Proxmox API token (see API Token Setup)
  • UV installed (pip install uv)

Option 1: Quick Install (Recommended)

  1. Clone and set up environment:

    # Clone repository cd ~/Documents/Cline/MCP # For Cline users # OR cd your/preferred/directory # For manual installation git clone https://github.com/canvrno/ProxmoxMCP.git cd ProxmoxMCP # Create and activate virtual environment uv venv source .venv/bin/activate # Linux/macOS # OR .\.venv\Scripts\Activate.ps1 # Windows
  2. Install dependencies:

    # Install with development dependencies uv pip install -e ".[dev]"
  3. Create configuration:

    # Create config directory and copy template mkdir -p proxmox-config cp config/config.example.json proxmox-config/config.json
  4. Edit proxmox-config/config.json:

    { "proxmox": { "host": "PROXMOX_HOST", # Required: Your Proxmox server address "port": 8006, # Optional: Default is 8006 "verify_ssl": false, # Optional: Set false for self-signed certs "service": "PVE" # Optional: Default is PVE }, "auth": { "user": "USER@pve", # Required: Your Proxmox username "token_name": "TOKEN_NAME", # Required: API token ID "token_value": "TOKEN_VALUE" # Required: API token value }, "logging": { "level": "INFO", # Optional: DEBUG for more detail "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s", "file": "proxmox_mcp.log" # Optional: Log to file } }

Verifying Installation

  1. Check Python environment:

    python -c "import proxmox_mcp; print('Installation OK')"
  2. Run the tests:

    pytest
  3. Verify configuration:

    # Linux/macOS PROXMOX_MCP_CONFIG="proxmox-config/config.json" python -m proxmox_mcp.server # Windows (PowerShell) $env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"; python -m proxmox_mcp.server

    You should see either:

    • A successful connection to your Proxmox server
    • Or a connection error (if Proxmox details are incorrect)

⚙️ Configuration

Proxmox API Token Setup

  1. Log into your Proxmox web interface
  2. Navigate to Datacenter -> Permissions -> API Tokens
  3. Create a new API token:
    • Select a user (e.g., root@pam)
    • Enter a token ID (e.g., "mcp-token")
    • Uncheck "Privilege Separation" if you want full access
    • Save and copy both the token ID and secret

🚀 Running the Server

Development Mode

For testing and development:

# Activate virtual environment first source .venv/bin/activate # Linux/macOS # OR .\.venv\Scripts\Activate.ps1 # Windows # Run the server python -m proxmox_mcp.server

Cline Desktop Integration

For Cline users, add this configuration to your MCP settings file (typically at ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{ "mcpServers": { "github.com/canvrno/ProxmoxMCP": { "command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python", "args": ["-m", "proxmox_mcp.server"], "cwd": "/absolute/path/to/ProxmoxMCP", "env": { "PYTHONPATH": "/absolute/path/to/ProxmoxMCP/src", "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP/proxmox-config/config.json", "PROXMOX_HOST": "your-proxmox-host", "PROXMOX_USER": "username@pve", "PROXMOX_TOKEN_NAME": "token-name", "PROXMOX_TOKEN_VALUE": "token-value", "PROXMOX_PORT": "8006", "PROXMOX_VERIFY_SSL": "false", "PROXMOX_SERVICE": "PVE", "LOG_LEVEL": "DEBUG" }, "disabled": false, "autoApprove": [] } } }

To help generate the correct paths, you can use this command:

# This will print the MCP settings with your absolute paths filled in python -c "import os; print(f'''{{ "mcpServers": {{ "github.com/canvrno/ProxmoxMCP": {{ "command": "{os.path.abspath('.venv/bin/python')}", "args": ["-m", "proxmox_mcp.server"], "cwd": "{os.getcwd()}", "env": {{ "PYTHONPATH": "{os.path.abspath('src')}", "PROXMOX_MCP_CONFIG": "{os.path.abspath('proxmox-config/config.json')}", ... }} }} }} }}''')"

Important:

  • All paths must be absolute
  • The Python interpreter must be from your virtual environment
  • The PYTHONPATH must point to the src directory
  • Restart VSCode after updating MCP settings

🔧 Available Tools

The server provides the following MCP tools for interacting with Proxmox:

get_nodes

Lists all nodes in the Proxmox cluster.

  • Parameters: None
  • Example Response:
    🖥️ Proxmox Nodes
    
    🖥️ pve-compute-01
      • Status: ONLINE
      • Uptime: ⏳ 156d 12h
      • CPU Cores: 64
      • Memory: 186.5 GB / 512.0 GB (36.4%)
    
    🖥️ pve-compute-02
      • Status: ONLINE
      • Uptime: ⏳ 156d 11h
      • CPU Cores: 64
      • Memory: 201.3 GB / 512.0 GB (39.3%)
    

get_node_status

Get detailed status of a specific node.

  • Parameters:
    • node (string, required): Name of the node
  • Example Response:
    🖥️ Node: pve-compute-01
      • Status: ONLINE
      • Uptime: ⏳ 156d 12h
      • CPU Usage: 42.3%
      • CPU Cores: 64 (AMD EPYC 7763)
      • Memory: 186.5 GB / 512.0 GB (36.4%)
      • Network: ⬆️ 12.8 GB/s ⬇️ 9.2 GB/s
      • Temperature: 38°C
    

get_vms

List all VMs across the cluster.

  • Parameters: None
  • Example Response:
    🗃️ Virtual Machines
    
    🗃️ prod-db-master (ID: 100)
      • Status: RUNNING
      • Node: pve-compute-01
      • CPU Cores: 16
      • Memory: 92.3 GB / 128.0 GB (72.1%)
    
    🗃️ prod-web-01 (ID: 102)
      • Status: RUNNING
      • Node: pve-compute-01
      • CPU Cores: 8
      • Memory: 12.8 GB / 32.0 GB (40.0%)
    

get_storage

List available storage.

  • Parameters: None
  • Example Response:
    💾 Storage Pools
    
    💾 ceph-prod
      • Status: ONLINE
      • Type: rbd
      • Usage: 12.8 TB / 20.0 TB (64.0%)
      • IOPS: ⬆️ 15.2k ⬇️ 12.8k
    
    💾 local-zfs
      • Status: ONLINE
      • Type: zfspool
      • Usage: 3.2 TB / 8.0 TB (40.0%)
      • IOPS: ⬆️ 42.8k ⬇️ 35.6k
    

get_cluster_status

Get overall cluster status.

  • Parameters: None
  • Example Response:
    ⚙️ Proxmox Cluster
    
      • Name: enterprise-cloud
      • Status: HEALTHY
      • Quorum: OK
      • Nodes: 4 ONLINE
      • Version: 8.1.3
      • HA Status: ACTIVE
      • Resources:
        - Total CPU Cores: 192
        - Total Memory: 1536 GB
        - Total Storage: 70 TB
      • Workload:
        - Running VMs: 7
        - Total VMs: 8
        - Average CPU Usage: 38.6%
        - Average Memory Usage: 42.8%
    

execute_vm_command

Execute a command in a VM's console using QEMU Guest Agent.

  • Parameters:
    • node (string, required): Name of the node where VM is running
    • vmid (string, required): ID of the VM
    • command (string, required): Command to execute
  • Example Response:
    🔧 Console Command Result
      • Status: SUCCESS
      • Command: systemctl status nginx
      • Node: pve-compute-01
      • VM: prod-web-01 (ID: 102)
    
    Output:
    ● nginx.service - A high performance web server and a reverse proxy server
       Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
       Active: active (running) since Tue 2025-02-18 15:23:45 UTC; 2 months 3 days ago
    
  • Requirements:
    • VM must be running
    • QEMU Guest Agent must be installed and running in the VM
    • Command execution permissions must be enabled in the Guest Agent
  • Error Handling:
    • Returns error if VM is not running
    • Returns error if VM is not found
    • Returns error if command execution fails
    • Includes command output even if command returns non-zero exit code

👨‍💻 Development

After activating your virtual environment:

  • Run tests: pytest
  • Format code: black .
  • Type checking: mypy .
  • Lint: ruff .

📁 Project Structure

proxmox-mcp/
├── src/
│   └── proxmox_mcp/
│       ├── server.py          # Main MCP server implementation
│       ├── config/            # Configuration handling
│       ├── core/              # Core functionality
│       ├── formatting/        # Output formatting and themes
│       ├── tools/             # Tool implementations
│       │   └── console/       # VM console operations
│       └── utils/             # Utilities (auth, logging)
├── tests/                     # Test suite
├── proxmox-config/
│   └── config.example.json    # Configuration template
├── pyproject.toml            # Project metadata and dependencies
└── LICENSE                   # MIT License

📄 License

MIT License

Publicly Shared Threads0

Discover shared experiences

Shared threads will appear here, showcasing real-world applications and insights from the community. Check back soon for updates!

Share your threads to help others
Related MCPs5
  • MCP SSH Server
    MCP SSH Server

    Secure Model Context Protocol (MCP) SSH server enabling remote command execution, file and directory...

    Added May 30, 2025
  • Xano MCP Server
    Xano MCP Server

    Python-based Model Context Protocol server enabling AI assistants to securely interact with Xano ins...

    Added May 30, 2025
  • ERPNext MCP Server
    ERPNext MCP Server

    Model Context Protocol server enabling seamless integration with ERPNext via API, offering authentic...

    Added May 30, 2025
  • Image Processor MCP Server
    Image Processor MCP Server

    A TypeScript-based Model Context Protocol server enabling creation, access, and summarization of tex...

    2 tools
    Added May 30, 2025
  • Chrome Debug MCP Server
    Chrome Debug MCP Server

    Model Context Protocol server enabling advanced browser automation with Playwright, featuring multi-...

    13 tools
    Added May 30, 2025