Which integrations are available for this server?

Allows restarting the MariaDB service on the managed VPS via the vps_restart_service tool, with a two-step confirmation process for safety. Allows restarting the NGINX service on the managed VPS via the vps_restart_service tool, with a two-step confirmation process for safety.

How do I use vpsdoctor-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by miguelmartt

Overview Schema Source Related Servers Discussions Admin

Python

Remote

vpsdoctor-mcp

Leer en español

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-mcp on the VPS, each one small enough to read in a minute (see scripts/).
A dedicated, unprivileged system user on the VPS that can, via a narrow sudoers rule, 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=true actually 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: vps-mcp-server

What it exposes

Tool	Read-only?	What it does
`vps_status`	yes	Services, disk, RAM, uptime, TLS certificate expiry, fail2ban summary, backup age
`vps_list_banned_ips`	yes	IPs currently banned in a fail2ban jail
`vps_restart_service`	no	Restart a service from your allowlist (two-step confirm)
`vps_unban_ip`	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.sh

This 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,mariadb

3. 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.sh restricts it in authorized_keys (no pty, no port/agent/X11 forwarding) and, via sudoers, 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_service and vps_unban_ip validate 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 (reusable n8n workflow templates, including a Telegram-based version of this same VPS-control idea).

License

MIT — see LICENSE.

Available Tools

4 tools

vps_list_banned_ipsA

Read-onlyIdempotent

List IP addresses currently banned by fail2ban in the given jail (default: sshd). Read-only.

ParametersJSON Schema

Name	Required	Description	Default
`jail`	No		sshd

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description says 'Read-only', which aligns with the readOnlyHint annotation. It adds 'currently banned' indicating a snapshot view. However, it does not disclose error behavior (e.g., what if jail doesn't exist) or output format. Since annotations already cover read-only and idempotent, the description adds minimal extra behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the action, and has zero waste. It conveys the core functionality and the key parameter in a compact form, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description covers the essential aspects: what it does, the jail parameter and its default, and read-only nature. It does not describe output format or error handling, but these are less critical given the tool's simplicity and the annotations. It is mostly complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains that 'jail' is the fail2ban jail and provides a default ('sshd'), giving meaning beyond the bare type. However, it does not describe possible values, whether it's optional (though default implies it), or any constraints. It covers the parameter's purpose adequately but not exhaustively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'IP addresses currently banned by fail2ban', with the jail parameter. This distinguishes it from siblings like vps_unban_ip (which removes bans) and vps_status (which shows status). No ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions a default jail ('sshd') but does not explicitly state when to use this tool versus alternatives like vps_unban_ip. It is implied that this is for checking banned IPs, but no explicit when/when-not guidance is provided. The read-only annotation offers some context, but the description itself lacks direct routing instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vps_restart_serviceA

DestructiveIdempotent

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.

ParametersJSON Schema

Name	Required	Description	Default
`confirm`	No
`service`	Yes

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds meaningful behavioral context beyond annotations: it warns of a brief service interruption, explains the preview behavior with confirm=false, and states that nothing executes until confirm=true. This complements the destructiveHint and idempotentHint annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence earns its place: purpose, allowed-scope restriction, interruption warning, and the safe confirmation flow. It is concise, front-loaded, and free of redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive restart operation with no output schema, the description fully covers what the tool does, what its constraints are, what side effects occur, and the required confirmation workflow. An agent has enough context to invoke it safely and correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain the parameters. It effectively explains confirm (false/omitted = preview, true = execute) and gives examples of valid service names, plus the ALLOWED_SERVICES constraint. It does not provide a formal parameter mapping, but the prose carries enough meaning for correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Restart a system service on the VPS' with concrete examples (nginx, mariadb). This clearly distinguishes it from sibling tools focused on status, banned IPs, and unbanning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage guidance: only services in ALLOWED_SERVICES can be restarted, and the two-step confirm=false → confirm=true flow is spelled out. It is unambiguous about how and when to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vps_statusA

Read-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.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only and idempotent. The description reinforces safety and adds what the snapshot includes (service states, disk, RAM, etc.), including a conditional backup age. This adds behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two crisp sentences, the key action and scope are front-loaded, and every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-param, no-output-schema tool, the description fully explains the return contents and safety. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist; schema coverage is trivially 100%. Baseline for 0-param tools is 4, and nothing more is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get a snapshot of the VPS') and enumerates the exact data points (service states, disk, RAM, uptime, TLS expiry, fail2ban, backup age). Clearly distinct from siblings which are for banned IPs and service actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Says 'Safe to call any time' which establishes it's a general read-only status check. Doesn't explicitly name alternatives, but the sibling tools are self-evidently different in purpose. Clear context without explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vps_unban_ipA

Idempotent

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.

ParametersJSON Schema

Name	Required	Default
`ip`	Yes
`jail`	No	sshd
`confirm`	No

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description reveals the critical behavioral trait that nothing runs until confirm=true, which is not visible in annotations or schema. It also clarifies that the first call is a dry-run validation, adding genuine transparency beyond the structured metadata.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The purpose is front-loaded, and the second sentence explains the confirmation flow without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the operation, the default jail, and the required confirmation flow. Despite no output schema, an agent has enough information to call the tool correctly in its two-phase pattern.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining the confirm parameter's semantics and noting the default jail. The ip parameter remains self-explanatory, though format or validation details are not provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Remove an IP address from a fail2ban jail.' It clearly identifies the operation and distinguishes it from siblings like vps_status and vps_list_banned_ips.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear procedural context by explaining the two-step confirm workflow: call with confirm=false to validate, then confirm=true to execute. It does not explicitly mention alternatives or exclusions, but the usage context is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.2.1Sep 15, 2026
- First observedvps_list_banned_ips
- First observedvps_restart_service
- First observedvps_status
- First observedvps_unban_ip

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored 2026-09-15 16:50 across 4 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

supportsheep
io.github.pooriaarab
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Customer Support Content Management Systems Marketing
1
emisarOAuth
dev.emisar
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Cloud Platforms Security Networking & Infrastructure
2353
sentinelOAuth
io.rootstuff
Uptime, SSL, DNS and domain monitoring you can talk to from Claude or any MCP client.
Monitoring Observability
21
PromptGuard Scan MCP
space.promptguardscan
Paid remote MCP for LLM security scans, jailbreak checks, analytics, checkout, and readiness.
Security Penetration Testing
2

Related MCP Servers

MCP VPS Manager
Shell Access Virtualization Monitoring
ARMeeru
A
license
Not graded
quality
D
maintenance
Enables LLMs to securely manage Virtual Private Servers via SSH, with features including command execution, file operations, system monitoring, and service management.
Updated a year ago (2025-08-23 03:08 UTC)
1
MIT
vps-mcp-server
Shell Access File Systems Virtualization
harbouli
F
license
A
quality
D
maintenance
Gives AI assistants full control over a VPS via SSH, enabling command execution, file management, service control, Docker and firewall management.
Updated 7 months ago (2026-02-13 13:19 UTC)
9
6
-
SSH MCP Server
Shell Access Command Line
honwee
A
license
A
quality
D
maintenance
Enables AI tools to manage SSH connections, execute commands, transfer files, and perform remote server diagnostics via MCP protocol.
Updated 6 months ago (2026-03-13 03:00 UTC)
17
4 npm
MIT
SSH MCP Server
Shell Access Command Line
fionarchl
A
license
Not graded
quality
D
maintenance
Enables MCP-compatible AI clients to remotely manage a Linux server via SSH, supporting file operations, Docker control, Git pulls, and arbitrary command execution.
Updated 3 months ago (2026-06-27 16:15 UTC)
6,170 npm
MIT