proxmox/docs/04-configuration/MCP_SETUP.md

MCP Server Configuration

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

This document describes how to configure the Proxmox MCP server for use with Claude Desktop and other MCP clients.

Claude Desktop Configuration

Step 1: Locate Claude Desktop Config File

The config file location depends on your operating system:

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

Step 2: Create or Update Config File

Add the Proxmox MCP server configuration. You have two options:

Option 1: Using External .env File (Recommended)

This is the recommended approach as it keeps sensitive credentials out of the config file:

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/home/intlc/projects/proxmox/mcp-proxmox/index.js"]
    }
  }
}

Important: The server automatically loads environment variables from /home/intlc/.env (one directory up from mcp-proxmox).

Option 2: Inline Environment Variables

If you prefer to specify environment variables directly in the config:

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/home/intlc/projects/proxmox/mcp-proxmox/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-ip-or-hostname",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "your-token-name",
        "PROXMOX_TOKEN_VALUE": "your-token-secret",
        "PROXMOX_ALLOW_ELEVATED": "false",
        "PROXMOX_PORT": "8006"
      }
    }
  }
}

Step 3: Create .env File (if using Option 1)

Create a .env file at /home/intlc/.env with the following content:

# Proxmox Configuration (REQUIRED)
PROXMOX_HOST=your-proxmox-ip-or-hostname
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-secret

# Security Settings (REQUIRED)
PROXMOX_ALLOW_ELEVATED=false  # Set to 'true' for advanced features

# Optional Settings
# PROXMOX_PORT=8006  # Defaults to 8006

⚠️ WARNING: Setting PROXMOX_ALLOW_ELEVATED=true enables DESTRUCTIVE operations (creating, deleting, modifying VMs/containers, snapshots, backups, etc.). Only enable if you understand the security implications!

Step 4: Restart Claude Desktop

After adding the configuration:

1. Save the config file
2. Restart Claude Desktop completely
3. Verify the server is loaded in Claude Desktop → Settings → Developer → MCP Servers
4. Test by asking Claude: "List my Proxmox VMs"

Proxmox API Token Setup

You have two options to create a Proxmox API token:

Option 1: Using the Script (Recommended)

Use the provided script to create a token programmatically:

./scripts/create-proxmox-token.sh <proxmox-host> <username> <password> [token-name]

Example:

./scripts/create-proxmox-token.sh 192.168.1.100 root@pam mypassword mcp-server

The script will:

1. Authenticate with your Proxmox server
2. Create the API token
3. Display the token values to add to your .env file

⚠️ Note: You'll need valid Proxmox credentials (username/password) to run this script.

Option 2: Manual Creation via Web Interface

1. Log into your Proxmox web interface
2. Navigate to Datacenter → Permissions → API Tokens
3. Click Add to create a new API token:
   • User: Select existing user (e.g., root@pam)
   • Token ID: Enter a name (e.g., mcp-server)
   • Privilege Separation: Uncheck for full access or leave checked for limited permissions
   • Click Add
4. Important: Copy both the Token ID and Secret immediately (secret is only shown once)
   • Use Token ID as PROXMOX_TOKEN_NAME
   • Use Secret as PROXMOX_TOKEN_VALUE

Permission Requirements

• Basic Mode (PROXMOX_ALLOW_ELEVATED=false): Minimal permissions (usually default user permissions work)
• Elevated Mode (PROXMOX_ALLOW_ELEVATED=true): Add permissions for Sys.Audit, VM.Monitor, VM.Console, VM.Allocate, VM.PowerMgmt, VM.Snapshot, VM.Backup, VM.Config, Datastore.Audit, Datastore.Allocate

Testing the MCP Server

You can test the server directly from the command line:

# Test server startup
cd /home/intlc/projects/proxmox/mcp-proxmox
node index.js

# Test listing tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node index.js

# Test a basic API call
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "proxmox_get_nodes", "arguments": {}}}' | node index.js

Available Tools

The Proxmox MCP server provides 55+ tools for interacting with Proxmox, including:

• Node management (list nodes, get status, get resources)
• VM and container management (list, create, delete, start, stop, reboot)
• Storage management (list storage, get details)
• Snapshot management (create, list, restore, delete)
• Backup management (create, list, restore, delete)
• Network management
• And much more...

See the mcp-proxmox README for the complete list of available tools.

Wormhole docs MCP server (read-only)

Purpose: Expose Wormhole’s AI documentation exports (see Wormhole AI Resources) as MCP resources, plus wormhole_doc_search over site-index.json. Documentation-only: no keys, no transactions.

Prerequisites:

1. Mirror docs (recommended): bash scripts/doc/sync-wormhole-ai-resources.sh — writes to third-party/wormhole-ai-docs/ (blobs gitignored; manifest.json may be committed).
2. Playbook: WORMHOLE_AI_RESOURCES_LLM_PLAYBOOK.md.

Install dependencies:

cd /home/intlc/projects/proxmox/mcp-wormhole-docs && pnpm install

Claude Desktop — add server (adjust path if your clone differs):

{
  "mcpServers": {
    "wormhole-docs": {
      "command": "node",
      "args": ["/home/intlc/projects/proxmox/mcp-wormhole-docs/index.js"]
    }
  }
}

Optional environment (in config env block or shell):

Variable	Meaning
WORMHOLE_DOCS_MIRROR	Override path to mirror directory (default: third-party/wormhole-ai-docs under repo root)
WORMHOLE_DOCS_FETCH	Set to 1 to fetch from https://wormhole.com/docs/... when a file is missing locally (host allowlisted only)
WORMHOLE_MAX_RESOURCE_BYTES	Max bytes returned when reading llms-full.jsonl (default 5242880); raise for larger inline reads or use the file on disk for RAG

Resources: URIs like wormhole://ai/llms.txt, wormhole://ai/site-index.json, wormhole://ai/categories/ntt.md, wormhole://ai/llms-full.jsonl.

Tools: wormhole_doc_search with { "query": "NTT", "limit": 10 }.

Manual smoke test (from repo root, after pnpm install in mcp-wormhole-docs):

cd /home/intlc/projects/proxmox/mcp-wormhole-docs && node index.js

Use your MCP client’s resource list / tool call UI, or the mcp-wormhole-docs README.

Separation: Keep this server separate from mcp-proxmox and ai-mcp-pmm-controller (infra vs PMM vs third-party docs).

Troubleshooting

Server Connection Errors

If Claude Desktop shows server connection errors:

1. Verify the path to index.js is correct and absolute
2. Ensure Node.js is installed and in your PATH
3. Check that dependencies are installed: cd mcp-proxmox && pnpm install
4. Test the server manually using the commands above

Environment File Not Found

If you see "Could not load .env file" warnings:

1. Verify the .env file exists at /home/intlc/.env (one directory up from mcp-proxmox)
2. Check file permissions: ls -la ~/.env
3. Verify the file contains valid environment variables

Authentication Errors

If you see authentication errors:

1. Verify your Proxmox API token is valid
2. Check that PROXMOX_HOST, PROXMOX_USER, PROXMOX_TOKEN_NAME, and PROXMOX_TOKEN_VALUE are all set correctly
3. Test the token manually using curl:

   curl -k -H "Authorization: PVEAPIToken=root@pam!token-name=token-secret" \
     https://your-proxmox-host:8006/api2/json/nodes
   

Permission Errors

If operations fail with permission errors:

1. Check that your API token has the required permissions
2. For basic operations, ensure you have at least read permissions
3. For elevated operations, ensure PROXMOX_ALLOW_ELEVATED=true is set and the token has appropriate permissions