VPS Ops

Name: VPS Ops
Author: koller-nexus

@koller-nexusMCP server · External

Stdio MCP server that inspects and (with confirmation) mutates one VPS over SSH.

Computer controlv0.1.0MITShell

Freeno charge per call

How to install

Runs on your machine from its package; the steps are below.

What it does

Reads
Writes
High impact

At most: moves money, runs code or commands, deletes data, or sends messages for you.

What it costs

Free

Odel charges nothing per call. The publisher may charge for its own service.

Runs locally over stdio

This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).

npm@koller-nexus/vps-ops-mcpv0.1.0

Run

npx -y @koller-nexus/vps-ops-mcp

MCP client config

{
  "mcpServers": {
    "vps-ops": {
      "command": "npx",
      "args": [
        "-y",
        "@koller-nexus/vps-ops-mcp"
      ]
    }
  }
}

README6 min readView on GitHub

vps-ops-mcp

A stdio MCP server that operates one VPS over SSH. Cursor and Codex start the process with bun and call read-only tools (host health, Unix debug, Docker, Compose, Swarm, firewall) plus mutation tools (restart, stop, start, prune). Mutations require an explicit confirmation.

Transport is stdio. Do not start the server as a long-lived process by hand: the client (Cursor or Codex) launches it.

Contributing

See CONTRIBUTING.md (branches, pull requests, verification) and ISSUE.md (how to file an issue).

Requirements

Bun
Python 3 (used by the registration scripts)
OpenSSH client (ssh on PATH)
A readable SSH private key with access to the remote user
On the remote host: Docker (and passwordless sudo -n for ufw, fail2ban, sshd -T, ss, and dmesg if you use those tools)

Configuration

bash

cp .env.example .env

Edit .env. The file is gitignored.

Variable	Required	Default	Purpose
`VPS_SSH_KEY_PATH`	yes	—	Absolute path to the private key. The process refuses to start if the file is missing or unreadable.
`VPS_HOST`	no	`vps.example.invalid`	SSH host (placeholder; set your own host).
`VPS_USER`	no	`ubuntu`	SSH user.
`VPS_PORT`	no	`22`	SSH port.
`VPS_COMPOSE_DIR`	no	—	Absolute Compose directory on the VPS. Without it, Compose tools require the `dir` argument.
`VPS_COMMAND_TIMEOUT_MS`	no	`30000`	Remote command timeout. Expiry returns `exit_code` 124.
`VPS_LOG_MAX_BYTES`	no	`200000`	Cap for `stdout`/`stderr`. Overflow is cut and `truncated` is `true`.
`VPS_ALLOW_MUTATIONS`	no	`true`	`false`, `0`, `no`, or `off` disables every mutation.
`VPS_SSH_KEY_PASSPHRASE`	no	—	Avoid. Prefer `ssh-agent`. Registration scripts do not copy this variable into the client.

VPS_COMPOSE_DIR must be absolute and match /^[a-zA-Z0-9/_.-]+$/ (it must start with /).

Installation

bash

bun install

npm package (requires Bun; the MCP Registry points at this artifact):

bash

bunx @koller-nexus/vps-ops-mcp

MCP Registry name: io.github.koller-nexus/vps-ops-mcp. The registry publishes metadata only after the package exists on public npm.

Register with clients

The scripts write MCP config from variables already exported in the shell. They do not load .env themselves. If you skip the export, the scripts fall back to their defaults (host, user, port, and a local key path).

Do this once at the repository root before each script:

bash

set -a
source .env
set +a

Each run backs up the destination file (*.bak.YYYYMMDDHHMMSS) and replaces only the vps-ops server. Other MCP servers stay in place.

Optional script variables:

Variable	Default	Purpose
`MCP_PROJECT_DIR`	this repository root	Source of the `src/index.ts` path.
`CURSOR_MCP_JSON`	`~/.cursor/mcp.json`	Cursor file to update.
`CODEX_CONFIG`	`~/.codex/config.toml`	Codex file to update.

VPS_COMPOSE_DIR is written into the client config only when it is set and non-empty.

Cursor

Global registration (applies in every workspace):

bash

./scripts/register-cursor-mcp.sh

The script writes ~/.cursor/mcp.json in this shape:

json

{
  "mcpServers": {
    "vps-ops": {
      "command": "bun",
      "args": ["/absolute/path/vps-ops-mcp/src/index.ts"],
      "env": {
        "VPS_HOST": "your.host",
        "VPS_USER": "ubuntu",
        "VPS_PORT": "22",
        "VPS_SSH_KEY_PATH": "/absolute/path/to/key",
        "VPS_COMMAND_TIMEOUT_MS": "30000",
        "VPS_LOG_MAX_BYTES": "200000",
        "VPS_ALLOW_MUTATIONS": "true"
      }
    }
  }
}

To scope it to one project, point the script at that project's mcp.json:

bash

CURSOR_MCP_JSON="/absolute/path/to/project/.cursor/mcp.json" ./scripts/register-cursor-mcp.sh

Then reload the Cursor window (Command Palette → Developer: Reload Window) or restart the server under Settings → MCP. The server appears as vps-ops.

Codex

bash

./scripts/register-codex-mcp.sh

The script writes ~/.codex/config.toml:

toml

[mcp_servers.vps-ops]
command = "bun"
args = ["/absolute/path/vps-ops-mcp/src/index.ts"]

[mcp_servers.vps-ops.env]
VPS_HOST = "your.host"
VPS_USER = "ubuntu"
VPS_PORT = "22"
VPS_SSH_KEY_PATH = "/absolute/path/to/key"
VPS_COMMAND_TIMEOUT_MS = "30000"
VPS_LOG_MAX_BYTES = "200000"
VPS_ALLOW_MUTATIONS = "true"

Close and reopen the Codex session so it rereads config.toml. If the CLI is on PATH, codex mcp list should show vps-ops.

Verify

Test SSH outside MCP with the same flags the server uses:

bash

ssh -i "$VPS_SSH_KEY_PATH" \
  -o BatchMode=yes \
  -o IdentitiesOnly=yes \
  -o StrictHostKeyChecking=accept-new \
  -p "${VPS_PORT:-22}" \
  "${VPS_USER}@${VPS_HOST}" \
  'uname -a'

In Cursor or Codex, ask the client to call vps_ping. The response is JSON:

json

{
  "exit_code": 0,
  "stdout": "...",
  "stderr": "",
  "duration_ms": 0,
  "truncated": false
}

A non-zero exit_code is an MCP error. If the process exits immediately with VPS_SSH_KEY_PATH is required or missing or unreadable, the variable never reached the client env — rerun the registration script with .env exported.

Tools

Every call returns exit_code, stdout, stderr, duration_ms, and truncated.

Read-only

Tool	Arguments	What it does
`vps_ping`	—	`uname -a`, `uptime`, `hostname`.
`vps_resources`	—	`df -h`, `free -h`, load average.
`vps_journal`	`unit`, `n?` (1–500, default 100)	`journalctl -u`. Unit from the allowlist (`docker`, `sshd`, `fail2ban`, `ufw`, `cron`, with or without `.service`) or a safe name ending in `.service`.
`docker_ps`	—	`docker ps -a` as JSON lines.
`docker_inspect`	`name`	`docker inspect`.
`docker_logs`	`name`, `n?` (1–1000, default 200), `since?`	`docker logs --tail --timestamps`.
`docker_stats`	—	`docker stats --no-stream`.
`docker_service_ls`	—	`docker service ls` as JSON lines (Swarm).
`docker_node_ls`	—	`docker node ls` as JSON lines (Swarm).
`compose_ps`	`dir?`	`docker compose ps` in `dir` or `VPS_COMPOSE_DIR`.
`host_listen`	—	`ss -lntup` (`sudo -n`, otherwise without sudo).
`host_failed_units`	—	`systemctl --failed --no-pager --full`.
`host_top`	—	Top 30 processes by memory (`ps aux --sort=-%mem`).
`host_dmesg`	`n?` (1–200, default 100)	`dmesg -T` + `tail` (`sudo -n`, otherwise without sudo).
`host_firewall`	—	`ufw status verbose` (`sudo -n`, otherwise without sudo).
`host_fail2ban`	`jail?`	`fail2ban-client status` (`sudo -n`).
`ssh_hardening_check`	—	Filtered `sshd -T`: port, password, root login, pubkey.

Container, service, image, and jail names must match ^[a-zA-Z0-9][a-zA-Z0-9_.-]*$.

Mutation

These require confirm: true. With VPS_ALLOW_MUTATIONS=false, all of them are rejected.

Tool	Extra arguments	Remote command
`docker_restart`	`name`	`docker restart`
`docker_stop`	`name`	`docker stop`
`docker_start`	`name`	`docker start`
`compose_up`	`dir?`, `services?`	`docker compose up -d`
`compose_restart`	`dir?`, `services?`	`docker compose restart`
`compose_pull_up`	`dir?`, `services?`	`docker compose pull` then `up -d`
`docker_rm`	`name`, `force_name`	`docker rm -f`. `force_name` must equal `name`.
`disk_cleanup_docker`	`confirm_volumes?`	`docker system prune -f`. Volumes only with `confirm_volumes: true`.

Security

Remote commands are fixed. There is no free-form shell tool.
Name and path arguments go through an allowlist and are quoted in the shell.
SSH uses BatchMode=yes, IdentitiesOnly=yes, and StrictHostKeyChecking=accept-new.
A mutation without confirm: true is rejected. docker_rm asks for the name twice. Volume prune requires confirm_volumes: true.
For a read-only client, register with VPS_ALLOW_MUTATIONS=false.

Similar modules

Browse Computer control