VPS Docker MCP — Erweitert

MCP-Server für Claude Code, der eine sichere VPS-Diagnose und Docker/Docker Compose-Verwaltung über SSH bietet.

Architektur

Claude Code
    |
    | MCP / stdio
    v
Local Python MCP server
    |
    | SSH / AsyncSSH
    v
VPS
    |
    +-- systemd
    +-- Docker
    +-- Docker Compose

Der MCP-Server läuft lokal. Auf dem VPS muss nichts lauschen.

Modulaufbau

src/vps_docker_mcp/
├── server.py          # MCP instance, wires modules together
├── ssh.py             # SSH config, run_ssh/run_many helpers
├── docker.py          # Docker and Docker Compose tools
└── infrastructure.py  # VPS diagnostics tools

Related MCP server: Docker/Hetzner MCP Server

Sicherheitsmodell

Dieses Projekt setzt bewusst keine willkürliche Shell-Ausführung frei.

Es gibt kein:

ssh(command)
execute(command)
bash(command)

Stattdessen ist jeder Vorgang ein vordefiniertes MCP-Werkzeug.

Argumente wie Container- und Dienstnamen werden mit einem restriktiven Allow-List-Muster validiert und vor dem Einfügen in Befehle shell-quotiert.

Die SSH-Host-Key-Prüfung ist über VPS_KNOWN_HOSTS aktiviert.

Verwenden Sie ein dediziertes Nicht-Root-SSH-Konto, z. B. deploy, mit Docker-Zugriff.

Anforderungen

• Python 3.11+

• uv

• SSH-Zugriff

• Docker auf dem VPS

• Docker Compose v2, wenn Compose-Werkzeuge verwendet werden

• deploy-Benutzer mit Berechtigung zum Ausführen von Docker

Installation

uv sync

Konfigurieren:

cp .env.example .env

Beispiel:

VPS_HOST=YOUR_VPS_IP
VPS_PORT=22
VPS_USER=deploy
VPS_SSH_KEY=~/.ssh/vps_mcp
VPS_KNOWN_HOSTS=~/.ssh/known_hosts
DOCKER_COMPOSE_DIR=/opt/news-bot
MAX_OUTPUT_CHARS=20000

SSH unabhängig testen:

ssh -i ~/.ssh/vps_mcp deploy@YOUR_VPS_IP docker ps

MCP testen:

uv run vps-docker-mcp

Es wartet auf MCP-Stdio-Eingabe. Das ist erwartet.

Claude Code-Konfiguration

Kopieren Sie .mcp.json.example in die projektweite .mcp.json, die von Claude Code verwendet wird, und ersetzen Sie den absoluten Pfad.

Beispiel:

{
  "mcpServers": {
    "vps-docker": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/home/me/projects/vps-docker-mcp-advanced",
        "run",
        "vps-docker-mcp"
      ]
    }
  }
}

Starten/Neustarten Sie dann Claude Code und überprüfen Sie den MCP-Status mit:

/mcp

Je nach Claude Code-Version können MCP-Server auch mit der Claude Code-CLI verwaltet werden.

Werkzeuggruppen

VPS-Diagnose

• system_info

• disk_usage

• top_processes

• network_info

• systemd_failed

• journal_errors

• diagnose_vps

Docker (schreibgeschützt)

• docker_ps

• docker_logs

• docker_inspect

• docker_stats

• docker_health

• docker_images

• docker_volumes

• docker_networks

• docker_disk_usage

Docker-Änderungen

• docker_restart

• docker_start

• docker_stop

Docker Compose

Schreibgeschützt:

• docker_compose_ps

• docker_compose_config

• docker_compose_logs

Ändernd:

• docker_compose_restart

• docker_compose_pull

• docker_compose_up

Eingeschränkte Diagnose

diagnostic_command erlaubt nur eine feste Liste:

• pwd

• whoami

• date

• df

• free

• uptime

• docker_version

• docker_info

Es akzeptiert keine beliebige Shell-Syntax.

Beispielhafte Claude Code-Anfragen

Check the VPS health.

Claude kann verwenden:

diagnose_vps

Für einen defekten Container:

Find out why news-bot is unhealthy.

Eine nützliche Diagnosesequenz ist:

docker_health
docker_ps
docker_logs
docker_stats
docker_inspect

Für ein allgemeines Ressourcenproblem:

Check whether the VPS is running out of RAM or disk space.

Claude kann inspizieren:

system_info
disk_usage
top_processes
docker_stats
docker_disk_usage

Dann:

Restart news-bot if the diagnosis indicates that a restart is appropriate.

Der Neustartvorgang ist ein separates änderndes Werkzeug.

Wichtige Produktionsempfehlung

Behalten Sie den eigenen Berechtigungs-/Genehmigungsmechanismus von Claude Code für ändernde Vorgänge aktiviert.

Der MCP-Server kennzeichnet ändernde Werkzeuge absichtlich in ihren Beschreibungen, aber MCP selbst sollte nicht als Autorisierungsgrenze behandelt werden.

Fügen Sie für einen Produktions-VPS keine willkürliche Shell-Ausführung hinzu, es sei denn, Sie akzeptieren das Risiko bewusst.

Zukünftige Verbesserungen

Gute nächste Erweiterungen wären:

• anwendungsspezifische Gesundheitschecks

• Docker-Container-Neustartschleifenerkennung

• OOM-Erkennung

• Festplattenwachstumserkennung

• systemd-Dienst-Neustartwerkzeuge

• konfigurierbare Allow-Liste von Compose-Projekten

• Audit-Logging

• Befehlsausführungs-Timeouts pro Werkzeug

• separate Lese- und Schreib-SSH-Anmeldeinformationen