Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
uvx mcp-ssh-gateway==7.0.0Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
SSH_SERVERS_CONFIG=<value> SSH_MCP_CACHE_DIR=<value> SSH_READ_ONLY=<value> SSH_COMMAND_BLACKLIST=<value> claude mcp add d00mus-mcp-ssh -- uvx mcp-ssh-gateway==7.0.0In einem Terminal ausführen.
{ "mcpServers": { "d00mus-mcp-ssh": { "command": "uvx", "args": [ "mcp-ssh-gateway==7.0.0" ], "env": { "SSH_SERVERS_CONFIG": "<value>", "SSH_MCP_CACHE_DIR": "<value>", "SSH_READ_ONLY": "<value>", "SSH_COMMAND_BLACKLIST": "<value>" } } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenVom Herausgeber
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.
SSH terminals for AI agents that know when a command is done: six tools, stateful shells, exit codes, router CLIs.
English · Русский
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.cd, variables and virtualenvs stay between calls. run without a session_id opens a new shell, so nothing is shared by accident.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).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.show interface, --More-- handled) or its Linux shell, through the same tools.sshd. Containers with bash, BusyBox ash, zsh, dash, fish and tcsh logins and a host without SFTP run in CI on every push.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".
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.
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 && '."}
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.
The gateway itself runs wherever Python 3.11+ runs (Linux, macOS, Windows).
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.
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_path (upload, download) works only after you start the gateway with --project-root <folder>, and then only inside that folder.known_hosts in the cache directory; a changed key is refused. verify_host: false turns the check off.${NAME} references in servers.json instead of the values. Logs mask password-like values (--log-output off writes no logs).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.
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):
Logs: one JSON-lines file per session and one per command under the cache directory; old files are pruned by age and size.
The gateway opens an interactive shell with a PTY and switches it to a quiet, machine-readable mode with one setup line: no echo, and a prompt that prints a marker containing the exit code. When the marker appears the command is over and the agent has its exit code. This also covers syntax errors, background jobs and Ctrl+C. An unclosed quote or heredoc is recognised by a second marker.
Routers whose login is a vendor CLI (Keenetic NDM) have no such shell. There the gateway learns the prompt from the login banner, removes the echo of the typed command, presses space at --More-- and treats a stable prompt as the end of the command. run(shell=false) uses the CLI, run(shell=true) enters the Linux shell behind it; a session keeps one mode.
Output goes into one line-based buffer per session with a single unread position. run and read advance it; tail jumps to the end; offset only looks. Lines longer than 1024 characters are split so that pages stay predictable.
run in parallel).sudo -s, su, bash) hides where commands end, so the gateway tells the agent to leave it. Use sudo <command> for root.They make different trade-offs (as of September 2026; read their READMEs before choosing):
ProxyJump, SSH CA and streaming SFTP; 14 tools. Choose it for production fleets that need approvals and an audit trail.npx) with a command whitelist, SOCKS and HTTP proxies, a bastion mode and MFA. Choose it for the smallest Node setup that needs proxies or MFA.This gateway chooses the other end: few tools, stateful shells, and an answer for every situation an agent gets stuck in.
docker build -t mcp-ssh-gateway .
docker run -i --rm \
-v /absolute/path/to/servers.json:/app/servers.json:ro \
-v /absolute/path/to/.ssh:/root/.ssh:ro \
-v /absolute/path/to/cache:/app/.ssh-cache \
mcp-ssh-gateway --servers-config /app/servers.json --cache-dir /app/.ssh-cache
The cache volume keeps known_hosts and the logs between runs.
pip install -r requirements.txt ruff mypy
python -m unittest discover -s tests -t . # unit tests; integration tests need Docker
ruff check . && mypy
Integration tests start real sshd containers and drive the gateway through the same JSON-RPC entry point a client uses. They skip themselves when Docker is missing (MCP_SSH_IT=0 skips on purpose). See CONTRIBUTING.md and the changelog. MIT-licensed.
SSH terminals for AI agents that know when a command is done: six tools, stateful shells, exit codes, router CLIs.
{ "mcpServers": { "d00mus-mcp-ssh": { "command": "uvx", "args": [ "mcp-ssh-gateway==7.0.0" ], "env": { "SSH_SERVERS_CONFIG": "<value>", "SSH_MCP_CACHE_DIR": "<value>", "SSH_READ_ONLY": "<value>", "SSH_COMMAND_BLACKLIST": "<value>" } } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Der Herausgeber nennt diese Umgebungsvariablen: SSH_SERVERS_CONFIG, SSH_MCP_CACHE_DIR, SSH_READ_ONLY, SSH_COMMAND_BLACKLIST.
MCP SSH läuft lokal über stdio.
Zuletzt geprüft: 2026-10-28. SSH terminals for AI agents that know when a command is done: six tools, stateful shells, exit codes, router CLIs.