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.

Network Model

This MCP server is useful when the remote server cannot access the internet, or when you do not want the remote server to use its own outbound network connection.

The MCP client and remote-ssh-mcp process run on your local computer. Requests are sent from the local computer to the remote server through SSH, so the remote server does not need internet access for MCP communication. The only network requirement is that your local computer can reach the server's SSH address and port.

This does not give remote commands internet access. Commands such as curl, wget, git clone, npm install, or pip install still run on the remote server and require network access from that server. To fetch files or data through the local computer, download them locally first and then use remote_ssh_write_file_base64, or use an SSH port forward where appropriate.

Quick Setup

Clone the repository, install dependencies, and run the interactive setup wizard:

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

The wizard:

1. Lists saved server profiles or creates a new profile.
2. Asks for the server IP/hostname, SSH user, port, and private-key path.
3. Detects an existing SSH key or generates an Ed25519 key.
4. Tests public-key authentication.
5. Offers to install the public key on the server. OpenSSH may request the server password once; the wizard never reads or stores it.
6. Saves the profile in ~/.remote-ssh-mcp/profiles.json.
7. Installs a profile-specific MCP entry into Codex Desktop/CLI and/or Claude Code.
8. Generates a profile-specific JSON config as a portable backup.

Restart the selected clients after setup. Codex Desktop and Codex CLI share the same ~/.codex/config.toml, so installing into either Codex surface enables both. Chinese instructions are available in docs/SETUP.zh-CN.md.

Multiple Servers

Run npm run setup again to add another server. Saved profiles are displayed before the connection questions, so an existing server can be selected without re-entering its address, user, port, or key path.

The default profile is installed as remote-ssh. Other profiles use distinct MCP server names:

default     -> remote-ssh
production  -> remote-ssh-production
staging     -> remote-ssh-staging

List saved profiles:

npm run profiles

Remove a local profile:

npm run profiles -- remove staging

Removing a profile does not remove its Codex or Claude Code MCP entry.

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.

Install From Source

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

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

MCP Client Configuration

The setup wizard installs clients using a profile name and profiles file:

{
  "mcpServers": {
    "remote-ssh": {
      "command": "node",
      "args": [
        "C:\\path\\to\\remote-ssh-mcp\\dist\\index.js"
      ],
      "env": {
        "REMOTE_SSH_PROFILE": "production",
        "REMOTE_SSH_PROFILES_FILE": "C:\\Users\\your-name\\.remote-ssh-mcp\\profiles.json"
      }
    }
  }
}

Direct SSH_HOST, SSH_USER, SSH_PORT, and SSH_IDENTITY_FILE configuration remains supported for compatibility. Explicit environment variables override profile values.

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

Variable	Default	Description
REMOTE_SSH_PROFILE	none	Saved profile to load
REMOTE_SSH_PROFILES_FILE	~/.remote-ssh-mcp/profiles.json	Local profiles file
SSH_HOST	none	Default hostname, alias, or IP address
SSH_USER	OpenSSH default	Username added to SSH_HOST when it has no @
SSH_PORT	OpenSSH default	SSH TCP port
SSH_BIN	platform OpenSSH	SSH executable path
SSH_IDENTITY_FILE	OpenSSH default	Private-key path passed to OpenSSH
REMOTE_SSH_HOST	none	Namespaced equivalent of SSH_HOST
REMOTE_SSH_USER	OpenSSH default	Namespaced equivalent of SSH_USER
REMOTE_SSH_PORT	OpenSSH default	Namespaced equivalent of SSH_PORT
REMOTE_SSH_BIN	platform OpenSSH	Namespaced equivalent of SSH_BIN
REMOTE_SSH_IDENTITY_FILE	OpenSSH default	Namespaced equivalent of SSH_IDENTITY_FILE
REMOTE_SSH_TIMEOUT_MS	60000	Default command timeout
REMOTE_SSH_MAX_OUTPUT_BYTES	1048576	Default captured bytes per output stream

Development

npm run typecheck
npm run build
npm run dev
npm run setup
npm run profiles

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

License

MIT. See LICENSE.