MCP SSH Gateway

What MCP SSH Gateway MCP server does

MCP SSH Gateway MCP server gives an MCP client access to remote machines over SSH. Each session is a real shell, so directory changes, environment variables, and virtual environments remain available for later commands in that session. Starting run without a session ID creates a new shell; passing the returned ID continues the existing one.

The gateway can work with configured Linux hosts and supports a Keenetic router CLI or router Linux shell through the same interface. It uses Paramiko as its direct dependency and runs locally as an MCP process rather than requiring a daemon or hosted service.

How it works

The gateway reports when a command has actually finished instead of inferring completion from a quiet terminal. Completed commands include an exit code, including non-zero codes for ordinary command failures. A command that exceeds the wait period returns a running status, after which the agent can call read to collect more output.

Interactive programs are represented as waiting_input when they request input, encounter a password prompt, or leave an unclosed quote. The agent can provide text with signal or interrupt the process with Ctrl+C. Long output is returned in pages, with fields indicating remaining lines and allowing the agent to read from an offset or request the tail. The session retains up to the documented buffer limit; output beyond that limit can be reported as dropped.

Setup and configuration

MCP SSH Gateway MCP server requires Python 3.11 or later, or installation through uvx, and SSH access to a host under the operator’s control. With an existing SSH configuration, start it using uvx mcp-ssh-gateway --import-ssh-config; hosts in the SSH config become available to the gateway. The package can also be installed with pip install mcp-ssh-gateway and launched as mcp-ssh-gateway.

For explicit definitions, provide a servers.json file containing server names, host addresses, users, and either key or password authentication. Use --servers-config with an absolute path to that file. Configuration values can reference environment variables, which must be supplied through the MCP client’s environment block. The README also documents an optional read-only host configuration.

The documented client configurations include Claude Desktop, Cursor, Claude Code, VS Code, and Codex. The server uses stdio transport in those examples. A first uvx launch may download the package, and the Codex example sets a startup timeout for that case.

Tools and capabilities

• server_list returns configured servers and their open sessions.
• run executes a command, creates a shell when no session ID is supplied, and accepts controls for waiting, timeouts, shell selection, and output lines.
• read retrieves unread output from a session, waits for running commands, or reads by tail and offset.
• signal sends standard input, Ctrl+C, or Ctrl+D.
• session_close closes a shell. Each server permits a limited number of sessions, with a default maximum of eight.
• file lists, reads, writes, and edits remote files over SFTP or through the shell when SFTP is unavailable. Reads support filtering, and edits can verify expected file content with a SHA-256 value.
• server_add can add a server to servers.json only when the gateway is started with --allow-add-server.

Limitations and notes

A new run call without a session ID does not share state with earlier shells. Agents should retain and reuse the returned session ID, then close sessions when finished. The gateway has a small fixed tool surface, and it does not provide a cwd argument; commands that need a particular directory should change directory within the shell command.

Non-zero command exit codes are returned as command results rather than MCP tool failures. Long-running commands require follow-up reads, while interactive commands require a signal response or interruption. Passwords and other referenced configuration variables must be provided by the client environment, and the SSH host must be reachable with valid credentials.