Remote SSH

This MCP server enables persistent SSH sessions with native GUI prompts for credentials, along with file transfers and background command support. It keeps connections alive across commands, reuses sessions for the same hosts, and secures secrets to protect your credentials during usage.

How to use

You enable this server in your MCP client by adding its command as an MCP server entry. Once configured, you can connect to SSH endpoints, provide credentials through native GUI prompts, and run commands across sessions without re-authenticating for every action.

How to install

Prerequisites: ensure Node.js is installed on your system.

Install the MCP server globally using the following command:

npm install -g remote-ssh-mcp

Configuration and usage notes

To use this MCP server, add it to your MCP client configuration so the client can start and communicate with the server.

Environment variables allow you to skip the GUI prompts by supplying credentials directly. If you provide credentials through the environment, the GUI prompts are bypassed.

Configuration details

Environment variables (optional) are supported to skip GUI prompts by supplying credentials directly. Example usage in your MCP client configuration:

{
  "mcpServers": {
    "ssh": {
      "command": "remote-ssh-mcp",
      "env": {
        "SSH_USER": "deploy",
        "SSH_PASSWORD": "secret"
      }
    }
  }
}

Host configuration file (optional)

You can define host defaults and per-host overrides in a host config file at the standard location used for SSH configurations. This allows you to specify usernames and key paths for recurring hosts.

{
  "defaults": { "username": "admin" },
  "hosts": {
    "prod.example.com": {
      "username": "deploy",
      "keyPath": "~/.ssh/deploy_key"
    }
  }
}

Testing and common workflows

Basic workflow example: connect to a server, run a command, and read output. Credentials are prompted via native GUI unless you supplied them via environment variables.

Security considerations

• Credentials are prompted using native OS dialogs and are not logged or written to disk.
• Per-process authentication tokens are used to limit exposure.
• A localhost-only credential helper enforces local access.
• Sessions expire after inactivity to minimize risk.

Troubleshooting and notes

If GUI prompts do not appear, ensure the required GUI tools are installed on your platform. For GUI prompts:

• Linux: zenity is required
• macOS: built-in macOS dialogs via osascript
• Windows: built-in PowerShell dialogs If you prefer non-GUI usage, provide credentials through environment variables or the host config file.

Available endpoints and capabilities

This server supports a set of endpoints to manage SSH sessions and transfers, including initiating connections, executing commands (with optional background mode), reading output history, and transferring files via SFTP.

Documentation and support

For the MCP client, connect to SSH endpoints, manage sessions, and leverage GUI prompts for credentials with persistent sessions across your commands.

Available tools

ssh_connect

Establish a connection to an SSH server and return a session identifier

ssh_exec

Execute a command on an active SSH session, with optional background mode

ssh_read_buffer

Read terminal output history from an active session

ssh_disconnect

Close an active SSH session