vps-ops-mcp

An MCP server that puts a long-running process on a remote VPS behind a handful of tools an AI assistant can call. Is it alive, what do the logs say, what has it produced, and an escape hatch for everything else.

Node, stdio transport, one dependency. Works with any MCP client.

Written first, in Node. The Python successor, approval-gate-mcp, adds a human approval gate, hot-reload parameters, and a wider dashboard. Use this one if you want something small; use that one if you want the gate.

Why

Checking on a background process means opening a terminal, finding the host, remembering the log path, and reading ps output. None of that is hard and all of it is friction, which means you check less often than you should.

This turns the same job into a question you ask in whatever assistant you already have open, and it keeps the answer structured enough to act on.

Tools

Tool	What it does
process_status	Running or not, PID, uptime, CPU, memory, disk usage, last log line
process_logs(lines)	Tail the last N lines of the log file, up to 500
record_summary(n)	Parse the JSON records the process writes into totals, a breakdown by type, and recent entries
wallet_balance	Optional. Read-only ERC-20 and native balance for a watch address
run_command(cmd)	Escape hatch. Arbitrary shell over SSH

Install

git clone https://github.com/WillyV347/vps-ops-mcp
cd vps-ops-mcp
npm install
cp .env.example .env      # then edit it

Register it with your MCP client:

{
  "mcpServers": {
    "vps-ops": {
      "command": "node",
      "args": ["/absolute/path/to/vps-ops-mcp/index.js"],
      "env": {
        "VPS_HOST": "your.host.or.ip",
        "VPS_USER": "your-ssh-user",
        "PROCESS_DIR": "/srv/my-process",
        "PROCESS_MATCH": "my_process.py"
      }
    }
  }
}

VPS_HOST, VPS_USER, and PROCESS_DIR have no defaults. The server prints what is missing and exits. A monitoring tool that quietly falls back to a host baked in by its author is a bug, not a convenience.

Everything else is optional:

Variable	Default	Purpose
PROCESS_MATCH	none	Pattern used to find the process in ps. Without it, process_status tells you so
LOG_FILE	$PROCESS_DIR/app.log	Log file to tail
RECORDS_FILE	$PROCESS_DIR/records.json	JSON array the process appends to
SSH_KEY	system default	Path to a private key
EVM_RPC_URL	none	Enables wallet_balance when set with the two below
WALLET_ADDRESS	none	Watch address, read-only
TOKEN_CONTRACT	none	ERC-20 contract to read
TOKEN_DECIMALS	18	Decimals for that token

Authentication is your existing SSH setup. The server shells out to the system ssh binary, so agents, hardware keys, and password managers that expose an agent all work unchanged. It never reads a private key itself.

The records file

record_summary reads a JSON array. Four keys are interpreted if present and everything else is ignored, so you do not have to reshape your data to use it:

[
  {
    "id": "job-1041",
    "record_type": "reindex",
    "resolved": true,
    "outcome": "win",
    "cost": 4.25,
    "result": 11.80,
    "label": "nightly reindex, shard 3"
  }
]

• record_type groups the breakdown
• resolved splits done from open
• outcome and result decide win or loss
• cost and result are summed into totals

Example session

> is the process up?

  Process RUNNING

  PID:      31882
  Uptime:   14h 22m (51720s)
  CPU:      0.6%
  Memory:   84.3 MB
  Disk:     212M

  Last log: 2026-08-18 22:03:11 cycle complete, 4 records written

> how's it doing overall?

  Record Summary

  Total:       128
  Resolved:    121 (74 win / 47 loss)
  Pending:     7
  Success:     61.2%
  Net result:  46.90
  Gross input: 512.25

  By type
    reindex: 88 (55W/29L/4P) | net 38.40 | 65%
    compact: 40 (19W/18L/3P) | net 8.50 | 51%

Output above is illustrative.

Notes on safety

• run_command runs arbitrary shell on the remote host. Scope the SSH user to what it actually needs rather than running everything as root.
• wallet_balance is read-only and never touches a key. Leave it unconfigured and the tool is not registered at all.
• No credential is stored in this repo. RPC providers put API keys in the URL path, so keep EVM_RPC_URL in the environment and out of your config files.
• StrictHostKeyChecking is set to accept-new: unknown hosts are trusted on first connect, changed host keys still fail.

License

MIT