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

{
  "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