MCP Remote Ssh

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:

{
  "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.