# 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:

```powershell
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](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:

```text
default     -> remote-ssh
production  -> remote-ssh-production
staging     -> remote-ssh-staging
```

List saved profiles:

```powershell
npm run profiles
```

Remove a local profile:

```powershell
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:

```powershell
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

```powershell
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:

```json
{
  "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

```powershell
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](LICENSE).