VPS Docker MCP — 高级版

为 Claude Code 提供的 MCP 服务器，支持安全的 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

安全模型

本项目有意不暴露任意 shell 执行。

没有：

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

相反，每个操作都是一个预定义的 MCP 工具。

诸如容器和服务名称等参数会通过严格的允许列表模式进行验证，并在插入命令前进行 shell 引用转义。

通过 VPS_KNOWN_HOSTS 启用 SSH 主机密钥检查。

使用专用的非 root SSH 账户（例如 deploy），并赋予其 Docker 访问权限。

要求

• 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

它不接受任意 shell 语法。

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，除非您有意接受风险，否则不要添加任意 shell 执行功能。

未来改进

下一步好的改进包括：

• 特定应用的健康检查

• Docker 容器重启循环检测

• OOM 检测

• 磁盘增长检测

• systemd 服务重启工具

• 可配置的 Compose 项目允许列表

• 审计日志

• 每个工具的命令执行超时

• 独立的只读和写入 SSH 凭据