MCP-Docker & MCP-Proxmox ¶

Sammel-Stack aus mehreren MCP-Servern (Model Context Protocol), die Docker-Hosts und einen Proxmox-Cluster für MCP-fähige Clients (z.B. Cherry Studio) zugänglich machen. Der Docker-Zugriff läuft über einen abgesicherten Docker-Socket-Proxy, der Proxmox-Zugriff read-only über einen PVEAuditor-Token.

Voraussetzungen ¶

• Docker-Socket des lokalen Hosts unter /var/run/docker.sock erreichbar
• Für die weiteren Docker-Hosts (Synology, Prod, Paperless): jeweils ein erreichbarer Docker-Daemon-TCP-Endpunkt (z.B. tcp://192.168.x.z:2375)
• Für Proxmox: ein PVEAuditor-Token (read-only) und eine passende config.json für proxmoxmcp-plus
• Ein MCP_API_KEY für den Proxmox-MCP-Server (selbst generiert, siehe unten)

Verzeichnisse anlegen ¶

Proxmox-VM ¶

mkdir /syno/proxmox-mcp
mkdir /syno/proxmox-mcp/proxmox-config

Synology ¶

Im Docker-Ordner folgende Verzeichnisstruktur anlegen:

proxmox-mcp
proxmox-mcp/proxmox-config

Proxmox-API-Token erstellen (für config.json) ¶

Dieser Token ist der Wert für auth.token_value in der config.json und stammt direkt aus Proxmox VE.

1. In der Proxmox-Weboberfläche zu Datacenter → Permissions → API Tokens navigieren
2. Add klicken
3. Als User einen dedizierten Benutzer wählen bzw. anlegen (z.B. mcp@pve)
4. Als Token ID einen Namen vergeben (z.B. readonly)
5. Privilege Separation aktiviert lassen (empfohlen)
6. Den erzeugten Token Secret sofort notieren (wird nur einmal angezeigt) → das ist auth.token_value
7. Unter Datacenter → Permissions dem Token die Rolle PVEAuditor zuweisen, um ausschließlich Lesezugriff zu gewähren

MCP_API_KEY erstellen (für den MCP-HTTP-Endpunkt) ¶

1. Einen zufälligen Schlüssel lokal generieren:

openssl rand -hex 32

2. Den erzeugten Wert als MCP_API_KEY in die Umgebungsvariablen des mcp-proxmox-Services eintragen
3. MCP-Clients müssen bei jeder Anfrage den Header Authorization: Bearer <MCP_API_KEY> mitsenden

Konfigurationsdatei vorbereiten ¶

In proxmox-config/ muss vor dem ersten Start eine config.json für proxmoxmcp-plus mit den Zugangsdaten zum Proxmox-Cluster (PVEAuditor-Token) abgelegt werden.

Konfigurationsdatei (config.json) ¶

{
  "proxmox": {
    "host": "192.168.x.c",
    "port": 8006,
    "verify_ssl": false
  },
  "auth": {
    "user": "mcp@pve",
    "token_name": "readonly",
    "token_value": "<token-value>"
  },
  "logging": {
    "level": "INFO",
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  },
  "security": {
    "dev_mode": true
  }
}

Compose-Stack ¶

services:
  docker-socket-proxy:
    image: tecnativa/docker-socket-proxy:latest
    container_name: docker-socket-proxy
    restart: unless-stopped
    environment:
      POST: 0
      CONTAINERS: 1
      IMAGES: 1
      NETWORKS: 1
      VOLUMES: 1
      INFO: 1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - mcp-docker
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:2375/_ping"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  # erster Host
  mcp-docker:
    image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
    container_name: mcp-docker
    restart: unless-stopped
    depends_on:
      - docker-socket-proxy
    environment:
      DOCKER_HOST: tcp://docker-socket-proxy:2375
    command: >
      uvx --with "mcp<2" mcp-proxy --host 0.0.0.0 --port 8933 --pass-environment
      -- uvx --with "mcp<2" mcp-server-docker
    ports:
      - "192.168.x.y:8933:8933"
    networks:
      - mcp-docker
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8933/status', timeout=3)"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

  # 2ter Host
  mcp-docker-syno:
    image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
    container_name: mcp-docker-syno
    restart: unless-stopped
    environment:
      DOCKER_HOST: tcp://192.168.x.z:2375
    command: >
      uvx --with "mcp<2" mcp-proxy --host 0.0.0.0 --port 8934 --pass-environment
      -- uvx --with "mcp<2" mcp-server-docker
    ports:
      - "192.168.x.y:8934:8934"
    networks:
      - mcp-docker
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8934/status', timeout=3)"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

  # 3.Host
  mcp-docker-prod:
    image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
    container_name: mcp-docker-prod
    restart: unless-stopped
    environment:
      DOCKER_HOST: tcp://192.168.x.a:2375
    command: >
      uvx --with "mcp<2" mcp-proxy --host 0.0.0.0 --port 8935 --pass-environment
      -- uvx --with "mcp<2" mcp-server-docker
    ports:
      - "192.168.x.y:8935:8935"
    networks:
      - mcp-docker
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8935/status', timeout=3)"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

  # 4.Host
  mcp-docker-paperless:
    image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
    container_name: mcp-docker-paperless
    restart: unless-stopped
    environment:
      DOCKER_HOST: tcp://192.168.x.b:2375
    command: >
      uvx --with "mcp<2" mcp-proxy --host 0.0.0.0 --port 8936 --pass-environment
      -- uvx --with "mcp<2" mcp-server-docker
    ports:
      - "192.168.x.y:8936:8936"
    networks:
      - mcp-docker
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8936/status', timeout=3)"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

  # Proxmox-Cluster (read-only über PVEAuditor-Token)
  mcp-proxmox:
    image: ghcr.io/rekklesna/proxmoxmcp-plus:0.5.14
    container_name: mcp-proxmox
    restart: unless-stopped
    environment:
      PROXMOX_MCP_MODE: mcp-http
      MCP_HOST: 0.0.0.0
      MCP_PORT: "8937"
      MCP_TRANSPORT: STREAMABLE_HTTP
      MCP_API_KEY: <mcp-api-key>
    volumes:
      # Für die Proxmox-VM verwenden
      - /syno/proxmox-mcp/proxmox-config/config.json:/app/proxmox-config/config.json:ro

      # Für die Synology verwenden
      # Volume-Nummer ggf. anpassen
      - /volume2/docker/proxmox-mcp/proxmox-config/config.json:/app/proxmox-config/config.json:ro
    ports:
      - "192.168.x.y:8937:8937"
    networks:
      - mcp-docker
    healthcheck:
      test: ["CMD", "python3", "-c", "import socket; socket.create_connection(('localhost', 8937), 3).close()"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

networks:
  mcp-docker:
    driver: bridge

Web-Zugriff ¶

Volumes ¶

Umgebung ¶

docker-socket-proxy ¶

mcp-docker / mcp-docker-syno / mcp-docker-prod / mcp-docker-paperless ¶

mcp-proxmox ¶

config.json (mcp-proxmox) ¶

Netzwerk: eigenes Bridge-Netzwerk mcp-docker (alle Services)
Neustart-Verhalten: unless-stopped (alle Services)