mcp-ssh-remote: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working in this repo.

Project overview

MCP server that wraps the system ssh binary (not a Node ssh2 implementation) so it inherits everything ~/.ssh/config supports: ProxyCommand, ProxyJump, magic-user bastions, identity files, etc. Single file: index.js. No build step, no dependencies beyond Node stdlib.

Running

# Direct
node index.js --host <hostname>

# Smoke test: pipe JSON-RPC to stdin, watch stdout
printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"execute_command","arguments":{"command":"hostname"}}}' \
  | node index.js --host <hostname>

<hostname> must resolve via ssh <hostname> from the user's shell.

Architecture

JSON-RPC stdio server. Lines in → dispatch → lines out.

• dispatch(msg) (bottom of file) routes initialize, tools/list, tools/call. tools/call → handleToolCall(name, args).
• handleToolCall is the big if chain — one branch per tool.
• ssh(remoteCmd, timeout) is the core transport. Wraps the command in bash -l -c <quoted> (login shell so conda/Slurm/modules load), runs spawnSync('ssh', [...sshArgs(), wrappedCmd]), returns {stdout, stderr, status, error}. One retry on ETIMEDOUT.
• sshWithStdin(remoteCmd, stdinData, timeout) — same, but pipes large input via stdin to avoid ARG_MAX. Used for write_file, edit_file.
• sshArgs() returns the ssh CLI args. Branches on NO_MULTIPLEX.

SSH multiplexing (important)

Multiplexing is off by default — NO_MULTIPLEX = process.env.MCP_SSH_MULTIPLEX !== '1'. Many jump hosts permit only one session per TCP connection (e.g. magic-user auto-forward bastions where the username encodes the target: user/target_ip/target_user). With multiplexing on, call #1 works, call #2+ hit Session open refused by peer, ssh client falls back to fresh connection per call, stderr noise leaks into every response, and under load the fresh connections flake.