mcp-ssh-remote

An MCP (Model Context Protocol) server that wraps the system ssh binary to execute commands on remote hosts — with full support for ProxyCommand, bastion hosts, jump hosts, and any configuration in ~/.ssh/config.

Built for workflows where your GPU/HPC server is behind a bastion host, has no internet access, and you want to develop locally with Claude Code while running jobs remotely.

Why this exists

Most SSH-based MCP servers (e.g. @fangjunjie/ssh-mcp-server) use Node's ssh2 library internally, which does not support ProxyCommand. If your remote server is behind a bastion host or requires a custom proxy setup defined in ~/.ssh/config, those servers simply cannot connect.

This server has no SSH implementation of its own — it calls the system ssh binary directly, so it inherits everything your shell SSH already supports: ProxyCommand, ProxyJump, identity files, ControlMaster, port forwarding, and so on.

Features

• Works with any ~/.ssh/config setup — ProxyCommand, ProxyJump, magic-user auto-forward bastions

• Optional SSH ControlMaster multiplexing — opt in with MCP_SSH_MULTIPLEX=1 for hosts where it works (off by default; see SSH multiplexing)

• Login shell wrapping — commands run via bash -l so your full environment (conda, Slurm, modules) is always available

• Slurm integration — submit, cancel, monitor jobs and read logs directly

• rsync support — sync local directories to the remote server through the bastion

• Safe file operations — large file writes piped via stdin (no shell arg limits), edit files with find-and-replace

SSH multiplexing

Multiplexing is off by default. Many jump hosts — especially magic-user auto-forward bastions (e.g. user/target_ip/target_user) — permit only one session per TCP connection. Every follow-up call then fails with Session open refused by peer, leaks stderr into the response, and flakes under load.

With multiplexing off, each call opens a fresh SSH connection. Slightly slower per call, but correct and reliable.

For hosts where multiplexing works (plain direct SSH, standard ProxyJump over a jumphost that supports session forwarding), opt in via env var:

{
  "mcpServers": {
    "ssh-remote": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-ssh-remote/index.js", "--host", "myserver"],
      "env": {"MCP_SSH_MULTIPLEX": "1"}
    }
  }
}

Requirements

• Node.js >= 14

• System ssh and rsync installed (openssh)

• The target host must be reachable via ssh <hostname> from your terminal

Installation

Via npx (no install needed):

npx mcp-ssh-remote --host myserver

Or clone and run directly:

git clone https://github.com/JasonLinjc/mcp-ssh-remote.git
node mcp-ssh-remote/index.js --host myserver

Claude Code Configuration

Add to your ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "ssh-remote": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-ssh-remote/index.js", "--host", "myserver"],
      "env": {}
    }
  }
}

Or with npx:

{
  "mcpServers": {
    "ssh-remote": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-ssh-remote", "--host", "myserver"],
      "env": {}
    }
  }
}

You can also add it via the Claude Code CLI:

claude mcp add ssh-remote -- node /path/to/mcp-ssh-remote/index.js --host myserver

Bastion / ProxyCommand example

If ~/.ssh/config contains:

Host myserver
  HostName 10.0.0.5
  User alice
  ProxyCommand ssh bastion nc %h %p

Then just pass --host myserver — the ProxyCommand is followed automatically.

Tools

File Operations

Slurm Job Management

Sync & Utilities

Typical Workflow

1. Edit code locally           →  Claude Code's native Edit/Write tools
2. Sync to remote              →  rsync_to_remote (quick) or git push + git_pull_remote (committed)
3. Submit a Slurm job          →  slurm_submit
4. Monitor training            →  slurm_status + slurm_log
5. Read results                →  read_file, grep_files

Example conversation:

You:    "Change the learning rate to 1e-4 in train.py"
Claude: [edits local file]

You:    "Sync and submit on gpu31 with 4 GPUs"
Claude: [rsync_to_remote] → [slurm_submit -p gpu31 --gres=gpu:4]

You:    "How's it going?"
Claude: [slurm_status] → [slurm_log]

Usage

node index.js --host <hostname>

<hostname> must match a host you can reach with ssh <hostname> — an IP, a hostname, or a Host alias from ~/.ssh/config.

License

MIT