# remote-ssh-mcp [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/the-nine-nation/remote-ssh-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 163  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/remote-ssh-mcp

## Description
Persistent stateful remote SSH sessions for AI agents via MCP + OpenSSH.

## Tools
Capabilities this server exposes over MCP:

- **ssh_hosts** — List allowed OpenSSH Host aliases discovered from the local ssh_config (and explicit allowlist). Returns only safe connection metadata: alias, hostname, user, port, proxy_jump. Never returns private keys, IdentityFile paths, agent sockets, or ProxyCommand. Pass reload=true after editing ~/.ssh/config to re-parse without restarting the MCP server. Use an alias from this list with ssh_open.
- **ssh_open** — Open a new persistent remote bash shell for an allowed ssh_config Host alias from ssh_hosts. Each call creates a clean session with a new id. Credentials come only from local OpenSSH configuration/agent; passwords and private keys are never accepted as arguments and must not be read from disk by the model.
- **ssh_run** — Start a non-interactive command in the same persistent shell identified by id. cwd and environment changes persist. The call waits at most wait_sec (default 10 seconds); if the command is still active it returns status=running without stopping it. Commands have no automatic execution timeout by default. Only an explicitly provided timeout_sec sends Ctrl-C at that deadline. Never retry a running command: poll with ssh_peek(wait_sec=...) so the MCP call blocks until idle or the wait expires; do not spam peeks with wait_sec=0. Call ssh_interrupt to stop it, or open another session for concurrent work. Only one foreground command may run per id. Do not use vim, top, password prompts, or other interactive TUI/input flows.
- **ssh_peek** — Observe the current foreground command and its latest output without starting another command. When status=running, optional wait_sec (default 0) long-polls this MCP call until the command finishes or the wait expires—prefer a positive wait_sec over busy-looping. wait_sec never stops the remote command. Returns the newest lines in chronological order, limited independently for stdout and stderr; lines defaults to 50 and is capped to protect model context. Use after ssh_run returns status=running. When idle, returns immediately with cwd, last exit code, and the latest lines from the completed command.
- **ssh_interrupt** — Send Ctrl-C to the current foreground process group and wait for the shell protocol to recover. The session is kept only when recovery is confirmed. Returns nothing_to_interrupt when idle.
- **ssh_list** — List all live sessions with host, cwd, state, last exit code, idle time, idle-reap countdown, and connection capacity. Use this to recover valid ids; never invent one.
- **ssh_close** — Close the remote shell and SSH connection, clean its private temporary directory, and invalidate the id. Close a dirty session and call ssh_open for a clean environment.

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

```json
"mcpServers": {
  "remote-ssh-mcp": {
    "command": "npx",
    "args": ["-y","@zyluo/remote-ssh-mcp"]
  }
}
```

## Documentation

## What remote-ssh-mcp MCP server does

The remote-ssh-mcp MCP server exposes stateful SSH access as MCP tools for AI agents. It runs on the machine hosting the MCP client and connects to remote systems through that machine’s OpenSSH installation. Remote hosts do not need Node.js, an MCP process, or a package installation; they need a normal SSH-accessible shell account and the command-line tools required by the session wrapper.

Each opened session represents a long-lived remote Bash process. Later commands use the same session, so changes such as `cd`, exported variables, and activated virtual environments remain available. Opening another session provides a separate environment when a clean state is needed.

## How it works

The MCP process starts the system `ssh` binary rather than implementing its own SSH protocol. OpenSSH continues to handle the local SSH configuration, known-host checks, agent use, jump hosts, and hardware-key workflows. Connections use host aliases from the local SSH configuration and are restricted to an exact allowlist; wildcard patterns are not accepted.

An agent first discovers permitted aliases with `ssh_hosts` or opens a connection with `ssh_open`. The returned session ID is then supplied to `ssh_run`, `ssh_peek`, and `ssh_interrupt`. A command runs for a bounded wait period. If it continues beyond that period, the tool reports that it is still running, allowing the agent to poll output instead of creating a new connection. `ssh_close` releases a session when it is no longer needed.

Command results separate standard output from standard error. Output is cleaned of terminal control noise and truncated at the head and tail when it exceeds the configured limits, reducing unnecessary MCP result size.

## Setup and configuration

Install and run remote-ssh-mcp on the local development machine or other host where the MCP client runs. The project targets Node.js 20 or newer and uses MCP stdio transport, so the client must be configured to launch the server as a local stdio process. The repository also publishes the package as `@zyluo/remote-ssh-mcp`.

Configure the SSH aliases, users, ports, keys, agent behavior, and ProxyJump routes in the local `~/.ssh/config`. The remote-ssh-mcp MCP server uses those OpenSSH settings and does not accept passwords, private-key text, or arbitrary SSH option arguments from the model. It enables batch operation and strict host-key checking.

## Tools and capabilities

- `ssh_hosts`: list safe metadata for allowed host aliases, with an option to reload configuration.
- `ssh_open`: create a persistent session for a required host alias, optionally assigning a label.
- `ssh_run`: execute a command in a session, with configurable initial wait and hard timeout values.
- `ssh_peek`: retrieve output from a running or recently executed command, with configurable line limits and waiting.
- `ssh_interrupt`: send an interrupt to a session when work is stuck or needs to stop.
- `ssh_close`: release the shell and SSH connection.

The server supports multiple sessions, idle reaping, session caps, and a JSONL audit log with hashed commands. It also includes a limited denylist for destructive command patterns and closes a session if recovery after an interrupt cannot be confirmed.

## Limitations and notes

This is a wrapper around OpenSSH, not a replacement SSH implementation. Access depends on the local client’s SSH configuration, credentials, known-host state, and the remote account’s available shell tools. The built-in command denylist is not a complete authorization policy. Output limits can omit part of a verbose command’s result, although head-and-tail truncation preserves both ends when possible.

The MCP transport is stdio, and the server is intended for MCP hosts that can launch local stdio servers. Remote machines do not run the MCP service; all SSH configuration and auditing described here occur on the machine running the server.

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