VPS Docker MCP — Advanced

MCP server for Claude Code that provides safe VPS diagnostics and Docker/Docker Compose management over SSH.

Architecture

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

The MCP server runs locally. Nothing needs to listen on the VPS.

Module layout

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
├── database.py        # PostgreSQL backup and stats tools
└── github.py          # GitHub Actions tools

Related MCP server: VPS-Guardian-MCP

Security model

This project intentionally does not expose arbitrary shell execution.

There is no:

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

Instead, every operation is a predefined MCP tool.

Arguments such as container and service names are validated with a restrictive allow-list pattern and shell-quoted before being inserted into commands.

SSH host key checking is enabled through VPS_KNOWN_HOSTS.

Use a dedicated non-root SSH account, e.g. deploy, with Docker access.

Credential isolation

SSH key — The VPS SSH key path lives only in .env and is loaded inside ssh.py at connection time. Agents never see the key. Enforced via Claude Code's permissions.deny rules:

"deny": ["Bash(ssh *)", "Bash(scp *)", "Bash(sftp *)", "Bash(rsync *)"]

GitHub token — The gh CLI is authenticated on the VPS. All GitHub operations run over SSH through this MCP server. Agents cannot call gh directly. Enforced via:

"deny": ["Bash(gh *)"]

Add both deny rules to ~/.claude/settings.json to lock down access.

Requirements

• Python 3.11+

• uv

• SSH access

• Docker on VPS

• Docker Compose v2 if Compose tools are used

• deploy user with permission to run Docker

• gh CLI installed and authenticated on the VPS if GitHub Actions tools are used

Installation

uv sync

Configure:

cp .env.example .env

Example:

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
GITHUB_REPO=acme/api
MAX_OUTPUT_CHARS=20000

Test SSH independently:

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

Test MCP:

uv run vps-docker-mcp

It will wait for MCP stdio input. That is expected.

Claude Code configuration

Copy .mcp.json.example to the project-level .mcp.json used by Claude Code and replace the absolute path.

Example:

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

Then start/restart Claude Code and inspect MCP status with:

/mcp

Depending on the Claude Code version, MCP servers can also be managed with the Claude Code CLI.

Tool groups

VPS diagnostics

• system_info

• disk_usage

• top_processes

• network_info

• systemd_failed

• journal_errors

• diagnose_vps

Docker read-only

• docker_ps

• docker_logs

• docker_inspect

• docker_stats

• docker_health

• docker_images

• docker_volumes

• docker_networks

• docker_disk_usage

Docker mutations

• docker_restart

• docker_start

• docker_stop

Docker Compose

Read-only:

• docker_compose_ps

• docker_compose_config

• docker_compose_logs

Mutating:

• docker_compose_restart

• docker_compose_pull

• docker_compose_up

Database (PostgreSQL)

Read-only:

• postgres_stats — show database sizes, active queries, and optionally top tables by size for a specific database

• postgres_list_backups — list backup files on the server, newest first

Mutating:

• postgres_backup_database — dump a single database to a custom-format .dump file; restore with pg_restore

• postgres_backup_all — dump all databases via pg_dumpall, compressed with gzip; restore with gunzip | psql

• postgres_download_backup — download a backup file from the server to a local directory via SFTP

All tools default to the container, user, and backup directory configured in .env (POSTGRES_CONTAINER, POSTGRES_USER, POSTGRES_BACKUP_DIR).

GitHub Actions

Read-only:

• gh_workflow_list — list all workflows in a repo

• gh_run_list — list recent runs, filterable by workflow, status, and limit

• gh_run_view — show summary and job status for a specific run

• gh_run_logs — fetch full or failed-only logs for a run

• gh_job_logs — fetch logs for a single job within a run

• gh_diagnose_last_run — fetch the most recent run (any status) and show its failed-step logs; answers "why did the last run fail?" in one call

• gh_diagnose_failure — find the latest failed run and show its error logs in one call

Mutating:

• gh_run_cancel — cancel an in-progress run

• gh_run_rerun — re-run a run, optionally failed jobs only

All tools accept a repo parameter (owner/repo). If omitted, they fall back to the GITHUB_REPO env var.

Restricted diagnostics

diagnostic_command only permits a fixed list:

• pwd

• whoami

• date

• df

• free

• uptime

• docker_version

• docker_info

It does not accept arbitrary shell syntax.

Example Claude Code requests

Check the VPS health.

Claude can use:

diagnose_vps

For a broken container:

Find out why news-bot is unhealthy.

A useful diagnostic sequence is:

docker_health
docker_ps
docker_logs
docker_stats
docker_inspect

For a general resource problem:

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

Claude can inspect:

system_info
disk_usage
top_processes
docker_stats
docker_disk_usage

Then:

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

The restart operation is a separate mutating tool.

For a broken CI build:

Why did the last build fail?

Claude can call:

gh_diagnose_failure

This finds the most recent failed run and returns the failed-step logs in one call. To scope it to a specific workflow:

gh_diagnose_failure(workflow="deploy.yml")

To browse recent runs and then dig into a specific one:

gh_run_list(status="failure", limit=5)
gh_run_logs(run_id="<id>", failed_only=True)

Development

Setup

uv sync
uv pip install -e ".[dev]"

Tests

pytest

77 tests cover all modules: utils, github, docker, infrastructure, database, and ssh. Tests use a FakeMCP helper that captures registered tool closures without starting a real MCP server. asyncssh.connect is mocked so SSH tests run without a real host.

Lint and type check

ruff check src tests
ruff format src tests
mypy src/vps_docker_mcp

Pre-commit

pre-commit install

Runs ruff check --fix and ruff format on every commit.

CI

GitHub Actions runs on every push to main and on pull requests: checkout → install → ruff → mypy → pytest.

Important production recommendation

Keep Claude Code's own permission/approval mechanism enabled for mutating operations.

The MCP server intentionally labels mutating tools in their descriptions, but MCP itself should not be treated as an authorization boundary.

For a production VPS, do not add arbitrary shell execution unless you deliberately accept the risk.

Future improvements

Good next additions would be:

• application-specific health checks

• Docker container restart-loop detection

• OOM detection

• disk growth detection

• systemd service restart tools

• configurable allow-list of Compose projects

• audit logging

• command execution timeouts per tool

• separate read-only and write SSH credentials

• GitHub Actions workflow dispatch (trigger a run)