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:

```json
{
  "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:

```json
{
  "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:

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

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

**Example:**
```bash
./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:

```bash
# 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](../../mcp-proxmox/README.md) for the complete list of available tools.

## Wormhole docs MCP server (read-only)

**Purpose:** Expose Wormhole’s **AI documentation exports** (see [Wormhole AI Resources](https://wormhole.com/docs/ai-resources/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](WORMHOLE_AI_RESOURCES_LLM_PLAYBOOK.md).

**Install dependencies:**

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

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

```json
{
  "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 }`.

**Cursor (this repo):** Project MCP config is [`.cursor/mcp.json`](../../.cursor/mcp.json) — server id **`wormhole-docs`**. After pulling changes: **Cursor Settings → MCP** (or **Tools & MCP**) should list it; if not, **reload the window** or restart Cursor. One-shot from repo root: `pnpm run mcp:wormhole` (stdio server; Cursor spawns it automatically when MCP is enabled).

**Health check (no MCP client):**

```bash
pnpm run verify:wormhole-mcp
```

**Manual smoke test** (from repo root, after `pnpm install` at workspace root or in `mcp-wormhole-docs`):

```bash
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](../../mcp-wormhole-docs/README.md).

**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:
   ```bash
   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