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.

Related MCP server: acp-mcp

Tools

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:

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