ssh2mcp

An MCP server that exposes one remote host, reached over ssh, as three tools: s_shell, s_xfer and s_file. It serves the "compile on the server, install on the phone" workflow: the agent keeps its workspace on the device and reaches the build machine through this server, rather than binding a second workspace.

Requirements

• Key-based ssh access to the host, configured as a Host alias in ~/.ssh/config. BatchMode=yes is forced, so a password prompt is a hard failure rather than a hang.

• Node.js with the MCP SDK, Express and Zod (npm install).

Related MCP server: ssh-chat-mcp

Transport and auth

• Listens on 127.0.0.1:6222 (SSH2MCP_BIND, MCP_PORT) and speaks Streamable HTTP only. POST /mcp is stateless, with a fresh server and transport per request; GET and DELETE /mcp answer 405.

• Every route requires Authorization: Bearer <token>, read per request from ~/.ssh2mcp-token (SSH2MCP_TOKEN_FILE); rotating the file needs no restart. The server refuses to start without one.

• localhostHostValidation() rejects DNS-rebinding hosts on every route.

• Loopback is not access control: any app on the device with the INTERNET permission can reach 127.0.0.1, while the commands themselves run with the privileges of the ssh user on the remote host. Keep the token at mode 600 and treat both ends as privileged.

Generate the token yourself, so that it never passes through a model:

python3 -c "import secrets;print(secrets.token_hex(24))" > ~/.ssh2mcp-token
chmod 600 ~/.ssh2mcp-token

Client: http://127.0.0.1:6222/mcp, header Authorization: Bearer <token>.

Permission levels

--perm ro|rw|full|selfcheck (default rw, or SSH2MCP_PERM). The live value is read per request from ~/.ssh2mcp-perm, so echo ro > ~/.ssh2mcp-perm switches without a restart; an unreadable or invalid file falls back to the startup level and never widens it. Raising the level to full from the CLI requires --force, and s2m st warns whenever the live level is not rw.

ro accepts a single command line: no >, <, ;, &&, ||, $() or backticks, and | only between allowlisted commands. find may not use -delete or -exec; java only -version; apksigner only verify; aapt2 only dump; date not -s; env is excluded because it executes its arguments. This is a guard against accidents, not a sandbox; a deliberately crafted equivalent command passes.

Tools

s_shell

{op: "run" | "bg" | "log" | "kill", command, cwd?, timeout_s?, job?, since?}

• run returns {exit, ms, stdout, stderr, timed_out}, keeping the first 70% and the last 30% of SSH2MCP_MAX_OUTPUT characters.

• run is bounded on both ends: the command is sent as timeout -k 5 <N> sh -c '<cmd>', so the deadline stops the remote process group as well, and the call returns at the deadline.

• run opts out of connection multiplexing (ControlPath=none; under ControlMaster a killed client leaves the pipe to the mux master open, and the call blocks until the remote command ends). Cost: about 0.6 s per call.

• bg writes the command to /tmp/s2m-<job>.cmd over stdin, so the payload needs no shell quoting, starts it with setsid, and returns a job id and pid. A background job is not bounded by timeout_s.

• log returns the chunk after since, a byte offset, with next_since and the state (running, done:<code>, gone), so a client polls without re-reading the log.

s_xfer

{op: "pull" | "push" | "status", local, remote, verify?}

• pull copies from the host to the device; push copies from the device to the host.

• Both resume from the first missing byte (tail -c +N on the sending side), write to <dest>.part, and rename only after sha256 matches on both ends. A mismatch renames the partial to .corrupt and fails; a truncated file is never reported as success.

• Bytes never enter the model context.

• push always verifies; verify: false is rejected, because a silently truncated file on the build machine is worse than a failure.

s_file

{op: "compare" | "stat" | "hash" | "list" | "read", path, side?,
 local_root?, remote_root?, local_path?, remote_path?}

• path with local_root and remote_root addresses the same relative path in both trees; an absolute path is used verbatim on both sides, and combining it with a root is rejected rather than resolved against one tree twice.

• To compare two files at different paths, pass local_path and remote_path.

• The tool is read-only. Writes live only in s_xfer, so a remote tree cannot be edited behind git's back.

• compare returns same, size-differs, content-differs or missing:<side>, plus the first differing line for text files up to 64 KB. Files above 128 MB are compared by size and mtime only.

Configuration

Local configuration

Values that describe a particular machine stay outside the repository. restart.sh sources ~/.ssh2mcp.env before starting the server:

SSH2MCP_SSH_HOST=myhost     # a Host alias from ~/.ssh/config
MCP_PORT=6222

Keep that file at mode 600. check-public.sh rejects commits that carry public IPv4 addresses, key material, GitHub tokens or personal mail addresses, and the pre-push hook runs it automatically:

git config core.hooksPath hooks

The bare repository on the build host is the source of truth; GitHub is a mirror.

git push origin main --tags   # bare repository on the build host
git push github main --tags   # mirror

Command line

node index.js [--perm <level>] [--port N]
node index.js --self-test     # offline: risk table and ro allowlist assertions
node index.js --self-check    # connectivity, remote toolchain, tmp roundtrip, token and perm state
node index.js --help

--self-test exits non-zero on failure; --self-check answers "is the build machine ready" in a single call.

s2m

~/ssh2mcp/s2m, symlinked into $PREFIX/local/bin as s2m and as five-letter aliases. Every subcommand goes through the MCP endpoint, so the permission level, the path jail and the risk table apply to the CLI exactly as they apply to the agent; there is no second code path that could bypass them.

Audit log

Every call appends one JSON line to ~/.ssh2mcp/audit.log: timestamp, tool, op, permission level, matched rule ids, exit code and duration. Commands are stored as a sha256 prefix rather than as text, so credentials on a command line do not land in the log. A permission change is recorded as perm-change with the previous level.

Known limits

• The risk table is a set of regular expressions over the command string. It catches the usual destructive shapes, not an obfuscated equivalent.

• ro cannot distinguish a read-only git invocation from a state-changing one beyond the subcommand allowlist.

• Stateless Streamable HTTP cannot stream text token by token; progress is delivered by polling bg with log.

• The run timeout is a hard cap on the host as well: a long build is killed mid-way if timeout_s stays at its 120 s default.

• One remote per instance (SSH2MCP_SSH_HOST). Several hosts need several instances on different ports.

License

MIT. See LICENSE.