proxmoxmcp

MCP for Proxmox integration in Cline Python-based implementation.

168 stars PythonDeveloper Kits Updated Nov 2, 2025

Documentation

🚀 Proxmox Manager - Proxmox MCP Server

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:

bash

# 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:

bash

# Install with development dependencies
   uv pip install -e ".[dev]"

3. Create configuration:

bash

# 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`:

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:

bash

python -c "import proxmox_mcp; print('Installation OK')"

2. Run the tests:

bash

pytest

3. Verify configuration:

bash

# 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:

⚙️ 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:

🚀 Running the Server

Development Mode

For testing and development:

bash

# 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`):

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:

bash

# 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:

code

🖥️ 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:

code

🖥️ 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:

code

🗃️ 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:

code

💾 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:

code

⚙️ 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:

code

🔧 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

code

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

Frequently asked questions

What is proxmoxmcp?

proxmoxmcp is MCP for Proxmox integration in Cline Python-based implementation.

How do I install proxmoxmcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is proxmoxmcp open source?

Yes — it is hosted on GitHub at https://github.com/canvrno/ProxmoxMCP and has 168 stars.

Related MCP tools

mcp

AWS MCP Servers — helping you get the most out of AWS, wherever you use MCP. Python-based implementation. Trusted by 6900+ developers.

6,922 Python

awsmcpmcp-client+6

mcpo

A simple, secure MCP-to-OpenAPI proxy server Python-based implementation. Trusted by 3500+ developers. Trusted by 3500+ developers.

3,594 Python

mcpmcp-servermcp-to-openapi+2

mcp-obsidian

MCP server that interacts with Obsidian via the Obsidian rest API community plugin Python-based implementation. Trusted by 2300+ developers.

2,353 Python

mcp-cli

Default Configuration: MCP CLI defaults to using Ollama with the gpt-oss reasoning model for local, privacy-focused operation without requiring API keys.

1,747 Python

minimax-mcp

Official MiniMax Model Context Protocol (MCP) server that enables interaction with powerful Text to Speech, image generation and video generation APIs.

1,032 Python

image-generationimage-to-videomcp+7

mcp-mem0

MCP server for long term agent memory with Mem0. Also useful as a template to get you started building your own MCP server with Python!

592 Python

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP