# faizbawa/mcp-remote-ssh [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/faizbawa/mcp-remote-ssh  
**GitHub Stars:** 10  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/faizbawa-mcp-remote-ssh

## Description
Full SSH access for AI agents with secret-safe environment injection and automatic output redaction. Persistent sessions, structured execution, SFTP, port forwarding — secrets are fed via stdin (invisible to ps) and scrubbed from all tool responses before reaching the LLM. uvx mcp-remote-ssh

## Tools
Capabilities this server exposes over MCP:

- **ssh_connect** — Connect to a remote host via SSH. Returns a session_id for use with all
other tools. Supports password and key-based authentication.
- **ssh_list_sessions** — List all active SSH sessions with their connection status and details.

Returns:
    List of session info dicts.
- **ssh_close_session** — Close an SSH session and release all its resources (shell, SFTP,
port forwards). WARNING: this kills any running processes in the session.
- **ssh_execute** — Execute a command on the remote host and return structured output.
Each call runs in an independent exec channel -- no state is shared
between calls (use ssh_shell_* tools for persistent state).

If secrets have been loaded via ssh_load_env_file, they are automatically
injected as environment variables for this command.
- **ssh_sudo_execute** — Execute a command with sudo on the remote host. If the user already
has passwordless sudo, leave sudo_password empty.

If secrets have been loaded via ssh_load_env_file, they are automatically
injected as environment variables for this command.
- **ssh_forward_port** — Create an SSH port forward (local -> remote). Connections to
127.0.0.1:local_port will be tunneled through SSH to remote_host:remote_port.

If local_port is 0, a random available port is chosen.
- **ssh_list_forwards** — List all active port forwards for an SSH session.
- **ssh_close_forward** — Close a specific port forward.
- **ssh_load_env_file** — Load environment variables from a LOCAL file (on the machine running
this MCP server) into the remote SSH session.

The file is read from the local filesystem -- it does NOT need to exist
on the remote host. Variable VALUES are never returned to the caller;
only variable names are confirmed.

Loaded values are:
1. Registered for automatic redaction -- any subsequent tool output
   (ssh_execute, ssh_shell_send, ssh_shell_read, ssh_read_remote_file)
   that contains a secret value will have it replaced with '***'.
2. Exported into the remote shell (if open) via builtins, avoiding
   exposure in the process tree on the remote host.
- **ssh_clear_secrets** — Clear all loaded secrets from the redaction registry. Secrets will
no longer be redacted from tool output. Does NOT unset the environment
variables from the remote shell.
- **ssh_upload_file** — Upload a local file to the remote host via SFTP.
- **ssh_download_file** — Download a file from the remote host to the local machine via SFTP.
- **ssh_read_remote_file** — Read a text file on the remote host and return its contents. For large
files, use max_bytes to limit the amount read.
- **ssh_write_remote_file** — Write text content to a file on the remote host via SFTP.
- **ssh_list_remote_dir** — List files and directories at a path on the remote host via SFTP.
- **ssh_shell_open** — Open a persistent interactive shell on the SSH session. The shell
preserves working directory, environment variables, and running processes
across multiple send/read calls. Ideal for screen/tmux, long builds, etc.

If a shell is already open, this is a no-op (returns existing shell info).
If secrets have been loaded via ssh_load_env_file, they are automatically
injected into the new shell.
- **ssh_shell_send** — Send text to the interactive shell. By default appends Enter (newline)
and waits briefly to capture output.
- **ssh_shell_read** — Read the current content of the interactive shell buffer. Use this to
poll for output from long-running commands without sending anything.
- **ssh_shell_send_control** — Send a control character to the interactive shell. Common keys:
"c" for Ctrl+C (interrupt), "d" for Ctrl+D (EOF), "z" for Ctrl+Z (suspend),
"l" for Ctrl+L (clear screen), "a" for Ctrl+A (screen prefix).
- **ssh_shell_wait** — Wait for the shell output to contain a specific pattern, or for the
output to stabilize (no new output for two poll intervals). Useful for
waiting on long-running commands to complete.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "mcp-remote-ssh": {
    "command": "uvx",
    "args": ["mcp-remote-ssh"]
  }
}
```

## Documentation

## What faizbawa/mcp-remote-ssh MCP server does

The faizbawa/mcp-remote-ssh MCP server exposes SSH operations through MCP. An agent can create a connection using password, private-key, or SSH-agent authentication, receive a session ID, and use that ID with later tools. Sessions can be listed or closed, and closing one also releases its shell, SFTP connection, and port forwards.

Command execution returns structured output rather than only a text stream. The server also supports sudo commands, local-to-remote port forwarding, remote file operations through SFTP, and reading text files from the remote host. These capabilities suit remote administration, test machines, CI hosts, lab systems, and development environments where an agent must perform several related operations over SSH.

## How it works

The MCP process runs on the local machine and opens SSH connections to the selected remote hosts. Ordinary execution uses an independent channel for each command, so working-directory changes and other shell state do not carry between calls. For stateful work, an agent can open an interactive shell; that shell keeps its current directory, environment, and running processes across send, read, wait, and control-character operations.

Secrets are loaded from a file on the local MCP host with `ssh_load_env_file`. The file uses common `.env` syntax, including comments, quoted values, and optional `export` prefixes. Values are retained in memory, supplied to the remote session, and registered for literal-value redaction. Responses from command execution, shell I/O, and remote text-file reads replace matching values with `***`. Clearing the secret registry stops future redaction but does not remove variables already exported in the remote shell.

## Setup and configuration

Install the package with `uvx mcp-remote-ssh`, or install it with `pip install mcp-remote-ssh`. A stdio MCP client configuration uses `uvx` as the command and `mcp-remote-ssh` as its argument:

```json
{
  "mcpServers": {
    "remote-ssh": {
      "command": "uvx",
      "args": ["mcp-remote-ssh"]
    }
  }
}
```

Connection credentials are supplied when calling `ssh_connect`; the material does not specify startup environment variables. The remote host must accept the selected SSH authentication method. Unknown host keys are accepted automatically through Paramiko's `AutoAddPolicy`, which avoids prompts for new machines but leaves first connections vulnerable to man-in-the-middle attacks.

## Tools and capabilities

The faizbawa/mcp-remote-ssh MCP server includes tools for:

- Creating, listing, and closing SSH sessions.
- Running regular and sudo commands with structured results.
- Opening persistent shells, sending input, reading buffered output, waiting for patterns or stable output, and sending control characters.
- Loading local environment files, registering secret values for redaction, and clearing the redaction registry.
- Uploading, downloading, reading, writing, and listing remote files through SFTP.
- Opening, listing, and closing local-to-remote port forwards. A requested local port of zero selects an available port.
- Recording command and shell activity, retrieving transcripts as text or JSONL, and saving transcripts to a local file.

Transcript recording is disabled by default and can be enabled when connecting or started later. Recorded command and shell output is redacted before it is stored. Transcripts kept in memory are lost when the session closes unless saved or retrieved first.

## Limitations and notes

Secret redaction covers literal values. Encoded or otherwise transformed versions of a secret are not detected. `ssh_clear_secrets` also does not unset variables that have already been exported in a remote shell.

Closing a session terminates running processes associated with that session. Remote file reads return text and can be limited with a maximum byte setting for larger files. The automatic host-key policy is suitable for ephemeral lab or CI machines but should be considered carefully on untrusted networks; the README suggests using a VPN or SSH bastion with known host keys in those environments.

_Full upstream README: https://allmcps.com/mcp/faizbawa-mcp-remote-ssh/readme_