vpsdoctor-mcp
This MCP server lets an AI client inspect and safely maintain a self-hosted Linux VPS over SSH using a limited set of vetted scripts.
Check VPS status: service states, disk/RAM usage, uptime, TLS certificate expiry, fail2ban summary, and backup age.
List IP addresses currently banned by fail2ban in a specified jail (default: sshd).
Restart an allowlisted service with a two-step confirmation flow; the first call only explains what would happen.
Unban an IP address from a fail2ban jail with IP validation and a two-step confirmation flow.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vpsdoctor-mcp how's the server doing?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
vpsdoctor-mcp
An MCP server that lets any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, and others) check the status of, and carry out safe maintenance on, a self-hosted Linux VPS — over plain SSH, with no proprietary agent installed on the server.
Ask "how's the server doing?" and get back service states, disk and RAM usage, uptime, TLS certificate expiry, and a fail2ban summary. Ask it to restart a service or unban an IP, and it will explain exactly what that means before touching anything.
Why
Most VPS-monitoring MCP servers either want you to install a heavyweight agent, or hand the model unrestricted shell access. This one does neither:
Just SSH. No agent, no extra service running on the VPS beyond what you already have.
A closed set of vetted scripts, installed once under
/opt/vpsdoctor-mcpon the VPS, each one small enough to read in a minute (seescripts/).A dedicated, unprivileged system user on the VPS that can, via a narrow
sudoersrule, run only those scripts — nothing else, no full root shell.Destructive actions require explicit confirmation. Restarting a service or unbanning an IP always takes two calls: the first one reports what would happen and does nothing; only a second call with
confirm=trueactually runs it. This mirrors the human-in-the-loop approach used across VerticeDev's other open-source agents.A restart allowlist enforced twice — once by the Python server, once again by the shell script itself on the VPS — so a bug on either side can't restart something you didn't intend to expose.
Related MCP server: SSH MCP Server
What it exposes
Tool | Read-only? | What it does |
| yes | Services, disk, RAM, uptime, TLS certificate expiry, fail2ban summary, backup age |
| yes | IPs currently banned in a fail2ban jail |
| no | Restart a service from your allowlist (two-step confirm) |
| no | Unban an IP from a fail2ban jail (two-step confirm) |
Setup
1. On the VPS
Copy the scripts/ folder to the VPS and run the installer as root:
scp -r scripts/ youruser@your-vps:/tmp/vpsdoctor-mcp-scripts
ssh youruser@your-vps
cd /tmp/vpsdoctor-mcp-scripts && sudo ./install.shThis creates a dedicated vpsdoctor-mcp system user, installs the scripts under /opt/vpsdoctor-mcp, writes a sudoers rule scoping that user to exactly those scripts, and generates a dedicated SSH keypair. It prints the next steps, including where to copy the private key.
Edit /opt/vpsdoctor-mcp/allowed_services.conf on the VPS to list the services you actually want restartable (one per line — it ships with nginx and mariadb as examples).
2. Where the server runs
git clone https://github.com/miguelmartt/vpsdoctor-mcp
cd vpsdoctor-mcp
pip install -e .
cp .env.example .env # then edit it.env:
VPS_HOST=your-vps-ip-or-hostname
VPS_PORT=22
VPS_USER=vpsdoctor-mcp
VPS_SSH_KEY_PATH=~/.ssh/vpsdoctor-mcp-key
SCRIPTS_DIR=/opt/vpsdoctor-mcp
ALLOWED_SERVICES=nginx,mariadb3. Point your MCP client at it
Claude Desktop / Claude Code (claude_desktop_config.json or equivalent — see examples/claude_desktop_config.json):
{
"mcpServers": {
"vpsdoctor": {
"command": "vpsdoctor-mcp",
"env": {
"VPS_HOST": "your-vps-ip-or-hostname",
"VPS_USER": "vpsdoctor-mcp",
"VPS_SSH_KEY_PATH": "/absolute/path/to/vpsdoctor-mcp-key",
"SCRIPTS_DIR": "/opt/vpsdoctor-mcp",
"ALLOWED_SERVICES": "nginx,mariadb"
}
}
}
}Any other MCP client that can launch a stdio server works the same way.
Security notes
The private key for the dedicated user should never leave the machine running the server.
install.shrestricts it inauthorized_keys(no pty, no port/agent/X11 forwarding) and, viasudoers, to running only the scripts in this repo — nothing else, even if that key is ever misused.The server refuses unknown SSH host keys (no trust-on-first-use). If this is the first time connecting to the VPS from wherever the server runs, pin its host key first:
ssh-keyscan -H your-vps >> ~/.ssh/known_hosts.Review
scripts/before installing — they're short and meant to be read, not trusted blindly.vps_restart_serviceandvps_unban_ipvalidate their input twice (once in Python, once in the shell script) before touching anything, and every executed restart/unban is logged at WARNING level for an audit trail.This project does not collect telemetry and makes no network calls other than the SSH connection you configure.
Extending it
Add a new script under scripts/, add it to the sudoers rule by re-running install.sh, and register a matching @mcp.tool() in src/vpsdoctor_mcp/server.py. Pull requests for additional read-only status checks are especially welcome.
Part of the VerticeDev open-source line
Sibling project: vertice-automations (self-hosted automations as small Python services, including VertiGuard: alerts and a Telegram DevOps bot built on this same VPS-control idea).
License
MIT — see LICENSE.
Available Tools
4 toolsvps_list_banned_ipsARead-onlyIdempotent
List IP addresses currently banned by fail2ban in the given jail (default: sshd). Read-only.
Inputs: jail.
vps_restart_serviceADestructiveIdempotent
Restart a system service on the VPS (e.g. nginx, mariadb).
Only services listed in the server's ALLOWED_SERVICES configuration can be restarted — anything else is refused before it ever reaches the VPS.
This causes a brief service interruption. Call once with confirm=false (or omitted) to see what would happen; nothing runs until you call again with confirm=true.
Inputs: service (required), confirm.
vps_statusARead-onlyIdempotent
Get a snapshot of the VPS: service states, disk, RAM, uptime, TLS certificate expiry, fail2ban summary, and (if configured) the age of the last backup. Safe to call any time — read-only.
Inputs: no named parameters.
vps_unban_ipAIdempotent
Remove an IP address from a fail2ban jail (default: sshd).
Call once with confirm=false (or omitted) to validate the IP and see what would happen; nothing runs until you call again with confirm=true.
Inputs: ip (required), jail, confirm.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct resource/action: status snapshot, banned IP list, service restart, and IP unban. Even though vps_status includes a fail2ban summary, it does not overlap with the detailed list of banned IPs.
All tools share the vps_ prefix, and three follow a verb_noun pattern (list_banned_ips, restart_service, unban_ip). vps_status is the only deviation, using a noun instead of a verb_noun structure, but the overall pattern remains clear.
Four tools is a well-scoped count for a focused VPS doctor utility. Each tool covers a distinct, necessary operation without unnecessary bloat or feature creep.
The tool set covers the core VPS doctor workflows: status overview, banned IP inspection, service restart, and IP unban. Minor gaps such as start/stop service or managing fail2ban jails exist, but they are not critical to the server's stated purpose.
Maintenance
Related MCP Connectors
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Manage Vozora VPS servers, SSH keys, firewalls, DNS and usage from an AI agent.
SSH client, server management and one remote MCP URL for your machines, with human approvals.
Termalin's hosted MCP server. Claude, ChatGPT or any MCP client runs commands, moves files over SFTP, queries databases and reads server metrics and monitoring alerts on your servers, keylessly through Termalin Connectors: no SSH key is handed over and no inbound port is opened. Per-host command policy and an audit log. Needs a termal.in Pro or Team account (new accounts start with a 14-day Pro trial).
Related MCP Servers
- FlicenseAqualityDmaintenanceGives AI assistants full control over a VPS via SSH, enabling command execution, file management, service control, Docker and firewall management.96-
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible AI clients to remotely manage a Linux server via SSH, supporting file operations, Docker control, Git pulls, and arbitrary command execution.ISC
- AlicenseAqualityDmaintenanceEnables secure, read-only inspection of a VPS over SSH through approved operations such as system health, disk usage, container logs, and service status, without giving the AI unrestricted shell access.81MIT
- AlicenseAqualityBmaintenanceEnables AI agents to safely monitor Linux VPS health, inspect Docker containers, retrieve service logs, and execute whitelisted recovery actions via MCP.31134 npmMIT