VPS Docker MCP — Avanzado

Servidor MCP para Claude Code que proporciona diagnóstico seguro de VPS y gestión de Docker/Docker Compose a través de SSH.

Arquitectura

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

El servidor MCP se ejecuta localmente. No es necesario que nada escuche en el VPS.

Diseño de módulos

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

Modelo de seguridad

Este proyecto intencionalmente no expone ejecución arbitraria de shell.

No hay:

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

En su lugar, cada operación es una herramienta MCP predefinida.

Argumentos como nombres de contenedores y servicios se validan con un patrón de lista de permitidos restrictivo y se escapan para shell antes de insertarse en los comandos.

La verificación de clave de host SSH está habilitada mediante VPS_KNOWN_HOSTS.

Use una cuenta SSH dedicada no root, por ejemplo deploy, con acceso a Docker.

Requisitos

• Python 3.11+

• uv

• Acceso SSH

• Docker en el VPS

• Docker Compose v2 si se usan herramientas de Compose

• Usuario deploy con permiso para ejecutar Docker

Instalación

uv sync

Configure:

cp .env.example .env

Ejemplo:

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

Pruebe SSH de forma independiente:

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

Pruebe MCP:

uv run vps-docker-mcp

Esperará la entrada stdio de MCP. Eso es esperado.

Configuración de Claude Code

Copie .mcp.json.example al .mcp.json a nivel de proyecto usado por Claude Code y reemplace la ruta absoluta.

Ejemplo:

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

Luego inicie/reinicie Claude Code e inspeccione el estado de MCP con:

/mcp

Dependiendo de la versión de Claude Code, los servidores MCP también se pueden gestionar con la CLI de Claude Code.

Grupos de herramientas

Diagnóstico de VPS

• system_info

• disk_usage

• top_processes

• network_info

• systemd_failed

• journal_errors

• diagnose_vps

Docker solo lectura

• docker_ps

• docker_logs

• docker_inspect

• docker_stats

• docker_health

• docker_images

• docker_volumes

• docker_networks

• docker_disk_usage

Mutaciones de Docker

• docker_restart

• docker_start

• docker_stop

Docker Compose

Solo lectura:

• docker_compose_ps

• docker_compose_config

• docker_compose_logs

Mutantes:

• docker_compose_restart

• docker_compose_pull

• docker_compose_up

Diagnóstico restringido

diagnostic_command solo permite una lista fija:

• pwd

• whoami

• date

• df

• free

• uptime

• docker_version

• docker_info

No acepta sintaxis de shell arbitraria.

Ejemplos de solicitudes a Claude Code

Check the VPS health.

Claude puede usar:

diagnose_vps

Para un contenedor roto:

Find out why news-bot is unhealthy.

Una secuencia de diagnóstico útil es:

docker_health
docker_ps
docker_logs
docker_stats
docker_inspect

Para un problema general de recursos:

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

Claude puede inspeccionar:

system_info
disk_usage
top_processes
docker_stats
docker_disk_usage

Luego:

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

La operación de reinicio es una herramienta mutante separada.

Recomendación importante para producción

Mantenga habilitado el mecanismo de permiso/aprobación propio de Claude Code para operaciones mutantes.

El servidor MCP etiqueta intencionalmente las herramientas mutantes en sus descripciones, pero MCP en sí mismo no debe tratarse como un límite de autorización.

Para un VPS de producción, no agregue ejecución arbitraria de shell a menos que acepte deliberadamente el riesgo.

Mejoras futuras

Buenas próximas adiciones serían:

• verificaciones de salud específicas de la aplicación

• detección de bucle de reinicio de contenedores Docker

• detección de OOM

• detección de crecimiento de disco

• herramientas de reinicio de servicios systemd

• lista de permitidos configurable de proyectos Compose

• registro de auditoría

• tiempos de espera de ejecución de comandos por herramienta

• credenciales SSH separadas de solo lectura y escritura