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アクセス権を持つ専用の非root 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認証情報の分離