MCP SSH Gateway

MCP SSH Gateway

SSH terminals for AI agents that know when a command is done.

Six tools, real shells that keep their state, the exit code the moment a command ends, and answers a small model can act on. One direct dependency (paramiko), no daemon, nothing in the cloud.

English · Русский

Why this one

• It knows when a command is done. The shell itself reports the end and the exit code, so echo hi returns in milliseconds, a failing command says exit_code: 2, and a three-minute build answers running after 10 seconds and is collected with read. No sleeps, no guessing from silence.
• Terminals with state. A session is one real shell: cd, variables and virtualenvs stay between calls. run without a session_id opens a new shell, so nothing is shared by accident.
• Made for small models. Six tools, about 1.6k tokens of descriptions in total. Every stop says what to do next (hint), pagers are off, a progress bar is one line, a wrong argument gets an answer that names the right call, and long output comes in pages (has_more, tail, offset).
• Questions do not hang. Continue? [y/N], a password prompt or an unclosed quote returns waiting_input. The agent answers with signal or presses Ctrl+C, and the shell keeps its state.
• Routers too. A Keenetic router CLI (show interface, --More-- handled) or its Linux shell, through the same tools.
• Tested against real `sshd`. Containers with bash, BusyBox ash, zsh, dash, fish and tcsh logins and a host without SFTP run in CI on every push.

Quick start

You need uv (or Python 3.11+ and pip) and SSH access to a host you control.

Already have `~/.ssh/config`? Add this to your MCP client, and every host in that file becomes a server (key or agent login):

{

"mcpServers": { "ssh": { "command": "uvx", "args": ["mcp-ssh-gateway", "--import-ssh-config"] } } }

This is the format of Cursor (~/.cursor/mcp.json) and Claude Desktop (claude_desktop_config.json); other clients are below. Restart the client and ask: *"List my SSH servers and show the disk usage on web."*

Want a password login, a router or a read-only host? Write a servers.json:

{

"servers": { "web": {"host": "192.168.1.10", "user": "deploy", "key_path": "~/.ssh/id_ed25519"}, "router": {"host": "192.168.1.1", "user": "admin", "password": "${ROUTER_PASSWORD}"} } }

and point the gateway at it with "args": ["mcp-ssh-gateway", "--servers-config", "/absolute/path/to/servers.json"]. Use an absolute path (clients do not start in your folder; on Windows escape backslashes in JSON) and give the gateway the variables it refers to in the client's "env" block. servers.json.example also shows a read-only production host. Without uv: pip install mcp-ssh-gateway and "command": "mcp-ssh-gateway".

Other clients

Claude Code

claude mcp add ssh --scope user -- uvx mcp-ssh-gateway --import-ssh-config

VS Code (.vscode/mcp.json: the top key is servers)

{

"servers": { "ssh": {"type": "stdio", "command": "uvx", "args": ["mcp-ssh-gateway", "--import-ssh-config"]} } }

Codex (~/.codex/config.toml, or codex mcp add ssh -- uvx mcp-ssh-gateway --import-ssh-config)

[mcp_servers.ssh]

command = "uvx" args = ["mcp-ssh-gateway", "--import-ssh-config"] startup_timeout_sec = 30 # the first uvx run downloads the package

The gateway is also listed in the official MCP Registry as io.github.d00mus/mcp-ssh-gateway, for the clients and directories that read it.

What the agent sees

Answers as a client receives them, captured from the test suite's Debian container (the host address and the disk figures are replaced with example values):

server_list()

→ {"servers":[{"server":"web","host":"192.168.1.10:22","user":"deploy"}]}

run(server="web", command="df -h /") # no session_id: a new shell is opened → {"session_id":"web/1","status":"completed","exit_code":0, "output":"$ df -h /\nFilesystem Size Used Avail Use% Mounted on\n/dev/vda1 40G 31G 7.2G 82% /\n"}

run(session_id="web/1", command="ls /nonexistent") # the same shell; a non-zero code is a result → {"session_id":"web/1","status":"completed","exit_code":2, "output":"$ ls /nonexistent\nls: cannot access '/nonexistent': No such file or directory\n"}

run(session_id="web/1", command="read -p 'Continue? [y/N] ' a; echo got:$a") → {"session_id":"web/1","status":"waiting_input", "output":"$ read -p 'Continue? [y/N] ' a; echo got:$a\nContinue? [y/N] ", "hint":"The program waits for input. Answer with signal action=stdin text=..., or stop it with signal ctrl_c."}

signal(session_id="web/1", action="stdin", text="y") → {"session_id":"web/1","status":"completed","output":"got:y\n","exit_code":0}

run(session_id="web/1", command="seq 1 500", lines=5) # long output comes in pages → {"session_id":"web/1","status":"completed","output":"$ seq 1 500\n1\n2\n3\n4\n","exit_code":0,"has_more":496}

read(session_id="web/1", tail=3) # just the end → {"session_id":"web/1","status":"completed","output":"498\n499\n500\n","exit_code":0,"skipped_lines":493}

read(session_id="web/1", offset=-20, lines=3) # scroll back; the unread position stays put → {"session_id":"web/1","status":"completed","output":"481\n482\n483\n","exit_code":0}

run(session_id="web/1", command="sleep 30", wait=1) → {"session_id":"web/1","status":"running","output":"$ sleep 30\n", "hint":"Still running. Call read(session_id='web/1') again, or stop it with signal ctrl_c."}

signal(session_id="web/1", action="ctrl_c") → {"session_id":"web/1","status":"interrupted","output":"\n","process_stopped":true}

A mistake gets an answer that names the right call. This is what a model that invents a cwd argument for run reads back:

{"error": "run has no argument 'cwd'. It takes: command, server, session_id, shell, wait, timeout, lines. To work in a folder, start the command with 'cd /path && '."}

Tools

Sessions are named server/N. A shell has state (folder, variables), so there is no default one: run without session_id always opens a new shell and returns its id, and that id continues the same shell. Close the shells you are done with.

What it works with

The gateway itself runs wherever Python 3.11+ runs (Linux, macOS, Windows).

Security

The agent has the reach of the SSH account you give it. What follows narrows the damage from mistakes; it does not replace a restricted account.

• Guardrails are mistake guards. read_only and command_blacklist (literal words, case-insensitive) look at the command text. Shell tricks, base64 or python -c get around them. For a real boundary use a restricted SSH account: a read-only shell, ForceCommand, separate credentials per trust level.
• Local files are off. local_path (upload, download) works only after you start the gateway with --project-root , and then only inside that folder.
• Host keys: a new host is trusted on first contact and its key is kept in known_hosts in the cache directory; a changed key is refused. verify_host: false turns the check off.
• Secrets: put ${NAME} references in servers.json instead of the values. Logs mask password-like values (--log-output off writes no logs).
• No listening port: the gateway talks MCP over stdio only. server_add does not exist unless you start it with --allow-add-server, and it only appends.

The full policy and how to report a problem: SECURITY.md.

Configuration

servers.json fields: host, user, port (22), key_path (~ and ${NAME} work), password and key_passphrase (only ${NAME} references are replaced, the rest is used as written), verify_host (true), description, extra_path (added to PATH), read_only, command_blacklist, max_sessions (8), shell (a POSIX shell to exec after login, for fish or tcsh accounts). The file is re-read while the gateway runs; unchanged servers keep their sessions.

Command line (none is required except a source of servers):

| --read-only, --command-blacklist a,b | Guardrails for every server (or $SSH_READ_ONLY,