Proxmox MCP Installation (Sillicon Mac) Intel below#

This guide details the process for installing the Proxmox Model Context Protocol (MCP) server and integrating it with Gemini-CLI to manage virtual machines and containers directly from the terminal.

1 Prerequisites#

Proxmox VE: Access to a Proxmox cluster or node.
Gemini-CLI: Installed via Homebrew or npm.
Python 3.10+: Required for the MCP server environment.
API Token: Created in Proxmox (Datacenter > Permissions > API Tokens). Ensure the token has sufficient permissions (e.g., PVEAuditor or PVEVMAdmin) and ‘Privilege Separation’ is unchecked.

2 Server Installation#

Run the following commands to clone the repository and set up the Python environment in a dedicated directory.

# Create and enter a dedicated directory for MCP servers
mkdir -p ~/mcp-servers
cd ~/mcp-servers

# Clone the Proxmox MCP repository
git clone https://github.com/bsahane/mcp-proxmox.git
cd mcp-proxmox

# Create a virtual environment
python3 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate

# Install requirements
pip install -r requirements.txt

# Install the package in editable mode to resolve module paths
pip install -e .

3 Gemini-CLI Configuration#

Update your Gemini-CLI settings file. Based on your preference, this file is located in your Obsidian vault.

File Path: /Users/marc/Obsidian/.gemini/settings.json

Add the proxmox block to the mcpServers object. Use the specific environment variable keys required by the bsahane implementation.

{
  "mcpServers": {
    "home-assistant": {
      "url": "http://[REDACTED_IP]:9583/[REDACTED_KEY]",
      "type": "http"
    },
    "proxmox": {
      "command": "/Users/marc/mcp-servers/mcp-proxmox/.venv/bin/python3",
      "args": [
        "-m",
        "proxmox_mcp.server"
      ],
      "env": {
        "PROXMOX_API_URL": "https://[REDACTED_IP]:8006",
        "PROXMOX_TOKEN_ID": "[REDACTED_USER]@[REDACTED_REALM]![REDACTED_TOKEN_ID]",
        "PROXMOX_TOKEN_SECRET": "[REDACTED_TOKEN_VALUE]",
        "PROXMOX_VERIFY": "false"
      }
    }
  }
}

3.1 Configuration Notes:#

PROXMOX_API_URL: Do not include /api2/json at the end of the URL; the server library appends this automatically.
PROXMOX_TOKEN_ID: Format is typically user@realm!tokenname (e.g., root@pam!gemini).
PROXMOX_VERIFY: Set to "false" to allow connections to nodes using self-signed SSL certificates.

4 Verification#

Restart Gemini-CLI to load the new configuration and verify the tools are active.

Launch Gemini:
```
gemini
```
List MCP Servers:
```
/mcp list
```
Verify that proxmox shows as Ready (118 tools).
Test Direct Connection: Run a specific tool command to ensure the API communication is functioning:
```
mcp_proxmox_proxmox-list-nodes
```

5 Troubleshooting#

ModuleNotFoundError: Ensure you ran pip install -e . inside the active virtual environment in the mcp-proxmox directory.
Disconnected Status: Check that the command path in settings.json points to the absolute path of the python3 executable inside your .venv/bin/ folder.
Hanging/Timeouts: Verify the PROXMOX_API_URL is reachable and the PROXMOX_TOKEN_SECRET is correct.

Proxmox MCP Installation (Intel Mac)#

This guide provides the terminal commands for Intel-based Macs using Homebrew Python 3.12. There are no brackets or parentheses in the commands to ensure they are safe for Zsh copy-pasting.

1. Prerequisites#

Ensure Python 3.12 is installed on the Intel Mac.

brew install python@3.12

---

## 1. Path Parity (CRITICAL)
Run this once to ensure the 1Password path synced from the MacStudio (`/opt/homebrew/bin/op`) is valid on the Intel Mac (`/usr/local/bin/op`):
sudo mkdir -p /opt/homebrew/bin && sudo ln -s /usr/local/bin/op /opt/homebrew/bin/op

---

## 2. Installation Sequence

Run these commands in order.
Setup directory and clone repo
mkdir -p ~/mcp-servers
cd ~/mcp-servers
rm -rf mcp-proxmox

Raw URL clone - NO BRACKETS
git clone https://github.com/bsahane/mcp-proxmox.git
cd mcp-proxmox

Create virtual environment using Python 3.12
/usr/local/bin/python3.12 -m venv .venv

Upgrade pip and install dependencies
./.venv/bin/python3 -m pip install --upgrade pip setuptools wheel
./.venv/bin/pip install -r requirements.txt
./.venv/bin/pip install -e .
---

## 3. Gemini-CLI Configuration

**File Path:** /Users/marc/.gemini/settings.json

```json
{
"mcpServers": {
 "proxmox": {
   "command": "/Users/marc/mcp-servers/mcp-proxmox/.venv/bin/python3",
   "args": [
     "-m",
     "proxmox_mcp.server"
   ],
   "env": {
     "PROXMOX_API_URL": "https://REDACTED_IP:8006",
     "PROXMOX_TOKEN_ID": "REDACTED_TOKEN_ID",
     "PROXMOX_TOKEN_SECRET": "REDACTED_TOKEN_SECRET",
     "PROXMOX_VERIFY": "false"
   }
 }
}
}

4. Verification#

Run the server manually to verify the environment.

/Users/marc/mcp-servers/mcp-proxmox/.venv/bin/python3 -m proxmox_mcp.server