VPS Docker MCP — 고급

Claude Code용 MCP 서버로, SSH를 통해 안전한 VPS 진단 및 Docker/Docker Compose 관리를 제공합니다.

아키텍처

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를 통해 활성화됩니다.

Docker 액세스 권한이 있는 전용 비루트 SSH 계정(예: deploy)을 사용하십시오.

요구 사항

• Python 3.11+

• uv

• SSH 액세스

• VPS의 Docker

• Compose 도구를 사용하는 경우 Docker Compose v2

• Docker 실행 권한이 있는 deploy 사용자

설치

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을 Claude Code에서 사용하는 프로젝트 수준의 .mcp.json으로 복사하고 절대 경로를 바꾸십시오.

예시:

{
  "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 서버는 Claude Code CLI로도 관리할 수 있습니다.

도구 그룹

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 자격 증명