remote-ssh-mcp

Generic MCP server for connecting an MCP client to a remote Linux or Unix host over SSH.

It provides remote shell commands, directory listing, text and binary file access, SSH port forwarding, and VS Code Remote-SSH URI generation. The server runs locally and reuses the OpenSSH installation, configuration, keys, agents, and ProxyJump settings already available on the user's machine.

Requirements

• Node.js 20 or newer

• OpenSSH client available as ssh

• SSH public-key authentication configured for the target host

• A local MCP client that supports stdio servers

Verify SSH before configuring the MCP client:

ssh 192.0.2.10 "hostname && whoami && pwd"

If your SSH setup needs a username or a non-default port, use the environment variables shown below or configure them in ~/.ssh/config.

Related MCP server: TermSSH MCP

Install From Source

git clone https://github.com/bbt567/remote-ssh-mcp.git
cd remote-ssh-mcp
npm install
npm run build

The repository does not store SSH passwords, private keys, or tokens.

MCP Client Configuration

Set SSH_HOST to the server IP address. SSH_USER and SSH_PORT are optional:

{
  "mcpServers": {
    "remote-ssh": {
      "command": "node",
      "args": [
        "C:\\path\\to\\remote-ssh-mcp\\dist\\index.js"
      ],
      "env": {
        "SSH_HOST": "192.0.2.10",
        "SSH_USER": "ubuntu",
        "SSH_PORT": "22"
      }
    }
  }
}

If the local SSH configuration already defines the user and port, only SSH_HOST is needed. A host alias, hostname, or user@host value is also accepted.

REMOTE_SSH_* variables are supported as the explicit namespaced equivalents. When both forms are present, REMOTE_SSH_* takes precedence.

Tools

• remote_ssh_check: Check the SSH connection and return remote identity details.

• remote_ssh_local_diagnostics: Inspect the local OpenSSH environment and connection.

• remote_ssh_exec: Run a shell command with optional working directory and environment.

• remote_ssh_list_dir: List a remote directory with ls -la.

• remote_ssh_read_text: Read a remote text file with a byte limit.

• remote_ssh_read_file_base64: Read a small remote binary file as base64.

• remote_ssh_write_text: Write UTF-8 text to a remote file.

• remote_ssh_write_file_base64: Decode base64 and write a remote file.

• remote_ssh_start_port_forward: Start a local SSH -L port forward.

• remote_ssh_list_port_forwards: List port forwards created by this process.

• remote_ssh_stop_port_forward: Stop a port forward created by this process.

• remote_ssh_uri: Generate a VS Code Remote-SSH URI and CLI command.

Every remote tool accepts an optional host field that overrides the configured target for that call. The command and file-write tools are intentionally powerful; review tool calls before approving them in your MCP client.

Environment Variables

Development

npm run typecheck
npm run build
npm run dev

The MCP server uses stdio. Logs are written to stderr so the MCP protocol stream remains clean.

License

MIT. See LICENSE.