VPS Docker MCP — Расширенный

MCP-сервер для Claude Code, который предоставляет безопасную диагностику VPS и управление Docker/Docker Compose через SSH.

Архитектура

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

MCP-сервер работает локально. На VPS не требуется ничего слушать.

Модульная структура

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

Модель безопасности

Этот проект намеренно не предоставляет произвольное выполнение команд.

Отсутствует:

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

Вместо этого каждая операция является предопределённым инструментом MCP.

Аргументы, такие как имена контейнеров и сервисов, проверяются по строгому разрешённому списку и экранируются перед вставкой в команды.

Проверка SSH-ключей хоста включена через VPS_KNOWN_HOSTS.

Используйте выделенную не-root SSH-учётную запись, например deploy, с доступом к Docker.

Требования

• Python 3.11+

• uv

• SSH-доступ

• Docker на VPS

• Docker Compose v2, если используются инструменты Compose

• пользователь deploy с разрешением на запуск Docker

Установка

uv sync

Настройка:

cp .env.example .env

Пример:

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 отдельно:

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

Проверьте MCP:

uv run vps-docker-mcp

Он будет ожидать ввода MCP через stdio. Это нормально.

Конфигурация Claude Code

Скопируйте .mcp.json.example в .mcp.json на уровне проекта, используемый Claude Code, и замените абсолютный путь.

Пример:

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

Затем запустите/перезапустите Claude Code и проверьте статус MCP с помощью:

/mcp

В зависимости от версии Claude Code, MCP-серверами также можно управлять через CLI Claude Code.

Группы инструментов

Диагностика VPS

• system_info

• disk_usage

• top_processes

• network_info

• systemd_failed

• journal_errors

• diagnose_vps

Docker только для чтения

• docker_ps

• docker_logs

• docker_inspect

• docker_stats

• docker_health

• docker_images

• docker_volumes

• docker_networks

• docker_disk_usage

Мутации Docker

• docker_restart

• docker_start

• docker_stop

Docker Compose

Только для чтения:

• docker_compose_ps

• docker_compose_config

• docker_compose_logs

Изменяющие:

• docker_compose_restart

• docker_compose_pull

• docker_compose_up

Ограниченная диагностика

diagnostic_command разрешает только фиксированный список:

• pwd

• whoami

• date

• df

• free

• uptime

• docker_version

• docker_info

Он не принимает произвольный синтаксис оболочки.

Примеры запросов к Claude Code

Check the VPS health.

Claude может использовать:

diagnose_vps

Для сломанного контейнера:

Find out why news-bot is unhealthy.

Полезная диагностическая последовательность:

docker_health
docker_ps
docker_logs
docker_stats
docker_inspect

Для общей проблемы с ресурсами:

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

Claude может проверить:

system_info
disk_usage
top_processes
docker_stats
docker_disk_usage

Затем:

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

Операция перезапуска — это отдельный мутирующий инструмент.

Важная рекомендация для производства

Оставьте включённым механизм разрешений/одобрения Claude Code для мутирующих операций.

MCP-сервер намеренно помечает мутирующие инструменты в их описаниях, но сам MCP не должен рассматриваться как граница авторизации.

Для производственного VPS не добавляйте произвольное выполнение команд, если только вы сознательно не принимаете на себя риск.

Будущие улучшения

Хорошими следующими дополнениями были бы:

• проверки работоспособности, специфичные для приложения

• обнаружение цикла перезапуска контейнера Docker

• обнаружение OOM

• обнаружение роста диска

• инструменты перезапуска служб systemd

• настраиваемый разрешённый список проектов Compose

• аудит логов

• тайм-ауты выполнения команд для каждого инструмента

• отдельные SSH-учётные данные для чтения и записи