Modern SSH for AI agents — cloud servers to BusyBox routers, with destructive commands blocked.
An MCP (Model Context Protocol) server that provides remote SSH access for AI agents, targeting environments ranging from cloud servers to BusyBox routers. It offers server-management capabilities while blocking destructive commands. The project is implemented in TypeScript and is intended to support workflows like remote server automation and management.
🛠️ Key Features
MCP server over SSH for AI agents
Supports remote server management and server automation
Destructive commands are blocked
TypeScript implementation
🚀 Use Cases
Debugging and development on remote systems
Managing servers remotely via SSH
Using AI agents (e.g., claude-code, codex, gemini-cli, qwen-code) for devops tasks
⚡ Developer Benefits
Uses Model Context Protocol (MCP) with an SSH-mcp-server interface
Helps reduce token usage by avoiding repeated debugging
SSH MCP Server — Remote server tools for AI agents
An SSH MCP server — a multitool that saves you and your AI agent time and tokens on debugging, development and server maintenance.
Run commands, move files, read logs and audit machines over SSH — a cloud VPS, a bare-metal box, or the BusyBox router sitting in your closet.
It uses the OpenSSH client already on your machine: your keys, your ~/.ssh/config, your jump hosts, your agent forwarding. Nothing bundled, nothing to compile, no native bindings.
Works with Claude Code, Codex CLI, Cline, opencode, Gemini CLI, Qwen Code, Hermes and other MCP clients.
The plugin reads ~/.claude/ssh-profiles.json unless SSH_PROFILES_FILE says otherwise, so
create that file first and the server comes up with your machines already loaded.
Requirements
Node.js 18+ and a system ssh client on PATH. On Windows, use a key-based profile;
password and passphrase profiles are not currently available.
Prefer a pinned version, offline work, or one less registry check per launch:
npm install -g @hypnosis/ssh-mcp-server, then use ssh-mcp-server as the command instead
of npx.
Who this is for
DevOps and SREs who want faster audits, incident checks and routine server work.
Vibe coders and indie builders who ship with an AI assistant and run what they build
on their own servers.
Sysadmins and platform engineers who want structured tools instead of an unrestricted
raw shell.
Developers and small teams running their own VPS without a dedicated operations team.
Homelab, NAS and router owners whose useful hardware has outlived its modern protocols.
Why an SSH MCP server instead of a raw shell
Fewer tokens, lower AI costs
A raw shell gives an AI agent a firehose: repeated commands, ASCII tables and log dumps.
It burns tokens turning that noise into a picture of the server — your money.
Faster server debugging
Purpose-built tools batch routine checks, cap noisy output and return the part that matters.
The agent spends less time translating terminal output and gets to the fix sooner.
Less guesswork, fewer AI mistakes
Structured answers say what was found, what could not be measured and what was truncated.
That leaves the agent less room to fill gaps with a hallucination — and gives you fewer bad
fixes, calmer deploys and more reliable code.
SSH compatibility: modern servers, legacy gear and Windows
Use your existing OpenSSH setup
No bundled SSH implementation, no native bindings, no rebuild per platform. Commands ride the
system ssh client, so your keys, your ~/.ssh/config, your jump hosts and your agent
forwarding all keep working exactly as they do in a terminal. When supported, one shared
multiplexed connection per destination means you authenticate once, not once per command.
SSH support for legacy servers, routers and NAS devices
Send a file to a router with a modern scp and you get this:
Nothing is broken — a current scp speaks the new protocol, and the router does not know it.
In a terminal you now go read a forum thread and come back with an extra flag. Here you do
nothing: the transfer is tried, the refusal is recognized, the old protocol is used instead,
and that machine is remembered so the next file goes straight there.
Fallbacks for older SSH clients and missing tools
Old gear gets a fallback, not a dead end. When a modern feature is missing, the server takes
the older road where it can:
Your machine
What you get
A router or NAS too small for modern file transfer
The file still lands — the old protocol is used automatically
A server from ten years ago
The workflow still works; it just opens a fresh connection per command instead of reusing one
A stripped-down image with no way to hash a file
The upload says "could not verify" instead of claiming a match nobody checked
A box where a tool simply is not installed
The answer says "not measured" — never a zero that reads as "nothing there"
Built for the Model Context Protocol
Built on the official MCP SDK, TypeScript throughout, 2500+ unit tests plus a live suite that
runs against real containers rather than mocks.
Raw SSH vs an SSH MCP server: the same job, both ways
SSH server health check
Situation: A deploy just went out. The server feels slow, and you do not know whether
disk, memory, services, containers or errors are to blame.
Question: “Is this box healthy?”
Raw SSH
console
$ uptime
10:42:17 up 18 days, 3:21, 2 users, load average: 0.42, 0.31, 0.28
$ df -hT
Filesystem Type Size Used Avail Use% Mounted on
/dev/sda1 ext4 40G 35G 5.0G 87% /
overlay overlay 40G 35G 5.0G 87% /var/lib/docker/overlay2/...
$ free -h
total used free shared buff/cache available
Mem: 7.7Gi 4.9Gi 612Mi 121Mi 2.2Gi 2.5Gi
$ systemctl --failed
UNIT LOAD ACTIVE SUB DESCRIPTION
● api-worker.service loaded failed failed API background worker
$ docker ps -a
CONTAINER ID IMAGE STATUS PORTS
8e14d0b41c2a api:latest Up 3 minutes 0.0.0.0:8080->8080/tcp
65b894af2430 worker:latest Exited (1) 2 minutes ago
$ ss -tulpn
Netid State Local Address:Port Process
tcp LISTEN 0.0.0.0:22 users:(("sshd",pid=842,fd=3))
tcp LISTEN 0.0.0.0:8080 users:(("docker-proxy",pid=1942,fd=4))
$ journalctl -p err --since -1h | tail -50
Aug 20 10:39:14 prod api-worker[22104]: database connection timed out
Aug 20 10:39:14 prod systemd[1]: api-worker.service: Failed with result 'exit-code'.
That is still an abridged result. A complete check needs more commands for CPU, service
states, container counts and recent errors, each with its own output format. Worse, a box
without ss can look like it has zero listeners when the port check never ran.
A full ssh_audit_baseline result can be longer than a handful of raw command outputs —
about 1,077 tokens versus 765 in our lab measurement. The saving comes from the complete
workflow, not from making one response shorter.
In a real troubleshooting session, purpose-built tools reduced 49 separate command calls to
4 MCP calls. Every additional call starts another model turn with the accumulated
conversation. Prompt caching can reduce the cost of repeated input, but new commands and
their output still consume context. Fewer round trips mean fewer tokens across the session,
less repeated analysis and a faster path to the answer.
Need the whole picture rather than the pulse?ssh_audit_baseline batches system, disk,
memory, ports, sshd, failed units, Docker, firewall and updates. Findings arrive as
CRITICAL / WARNING / OK; unmeasured sections are named instead of silently reading as zero.
Linux server log search
Situation: The API is timing out, but the same message may be in nginx, syslog,
journald or an application log you cannot read with your normal user.
Question: “Where did that error come from?”
Raw SSH
console
$ grep -i "timeout" /var/log/nginx/error.log
2026/08/20 10:38:54 [error] upstream timed out while reading response header
$ grep -i "timeout" /var/log/syslog
Aug 20 10:39:14 prod api-worker[22104]: database connection timed out
$ grep -i "timeout" /var/log/app/*.log 2>/dev/null$ journalctl -u api --since "1 hour ago" | grep -i timeout
Aug 20 10:39:14 prod api[22104]: database connection timed out after 30000ms
The third command looks clean, but 2>/dev/null also hid a permission error. "Nothing
matched" and "nothing was read" now look identical. A busy log can also return thousands of
lines and push the rest of the incident out of the agent's context.
{"matches":34,"lines":[{"file":"/var/log/nginx/error.log","line":4821,"text":"upstream timed out while reading response header","context":false},{"file":"/var/log/nginx/error.log","line":4822,"text":"client closed connection","context":true}],"files_searched":6,"files_unreadable":["/var/log/app/private"],"files_skipped":12,"files_undated":[],"limited":false,"truncated":false}
What the agent gains
Raw SSH
Structured MCP
Your gain
Four searches and four outputs
One search across files and globs
Fewer tokens and round trips
Permission errors can disappear
files_unreadable names every missed path
No false "logs are clean" conclusion
Output can grow without a useful ceiling
limited and truncated expose every cutoff
Safer decisions from partial results
since uses the server's clock, namesOnly: true returns only matching paths, and
ssh_log_tail reads the last N lines from several logs in one call.
Safe remote config edits
Situation: You need to replace an nginx config on a live server. A dropped connection,
wrong mode or unchecked copy could leave the service with a broken file.
Question: “Can I replace this config without leaving a partial file?”
Exit code zero says the shell finished. It does not prove which bytes landed, and >
truncated the old file before the first byte of the new one arrived. If the connection drops
mid-write, the service is left with a partial config.
verified has three honest outcomes: verified, unavailable when the server has no hash
tool, and skipped when verification was not requested. For reads, ssh_file_read accepts a
list of paths; ssh_file_list handles globs, recursion, sizes and modes.
Run batch SSH commands with sudo
Situation: A deploy is ready, but nginx syntax, service state and recent errors must all
be checked before traffic moves. One failed check should not disappear inside a combined dump.
Question: “Did every preflight check pass?”
Raw SSH
console
$ ssh admin@server.example.com 'sudo nginx -t'
nginx: configuration file /etc/nginx/nginx.conf test is successful
$ ssh admin@server.example.com 'sudo systemctl is-active nginx'
active
$ ssh admin@server.example.com 'sudo tail -5 /var/log/nginx/error.log'
2026/08/20 10:38:54 [error] upstream timed out while reading response header
Three connections return three unrelated outputs. If the commands are joined with ;, the
shell reports only the last exit code; if they are joined with &&, later checks disappear
after the first failure.
{"commands":[{"command":"nginx -t","exit_code":0,"truncated":false,"clipped_bytes":0,"stdout":"","stderr":"nginx: configuration file /etc/nginx/nginx.conf test is successful\n"},{"command":"systemctl is-active nginx","exit_code":0,"truncated":false,"clipped_bytes":0,"stdout":"active\n","stderr":""},{"command":"tail -5 /var/log/nginx/error.log","exit_code":0,"truncated":false,"clipped_bytes":0,"stdout":"2026/08/21 09:14:02 [error] upstream timed out\n","stderr":""}],"job_id":null}
What the agent gains
Raw SSH
Structured MCP
Your gain
Three calls and unrelated outputs
One ordered command list
Fewer round trips
A combined shell can hide intermediate status
Every command keeps its own exit_code
No missed failed check
sudo and quoting are repeated in command text
sudo applies to the whole batch
Fewer quoting mistakes
The destructive-command guard checks the complete list before the first command runs. If one
entry is refused, every other entry is marked as not run and nothing is sent to the server.
Each command carries its own stdout and stderr. A command that ran and printed nothing
has an empty string; a command that never ran has no such field at all, so the two cannot be
confused. Output over 128 KB per command keeps both ends — the head for tables, the tail for
logs — with a seam in between naming the amount, and clipped_bytes says how much was cut.
Cutting happens on byte boundaries and steps back to the edge of a character, so a clipped
answer never carries a replacement mark.
sudo reaches the server without a terminal: the profile's answer is handed to sudo on
standard input. Which secret that is comes from sudoPassword when the profile names one and
from password otherwise — a profile that logs in by key has no login password at all, and
where a machine keeps the two apart the login one is the wrong answer. Where there is nothing
to answer with, the reply says so and names the ways out, instead of leaving sudo's own advice
about -S and askpass helpers. A command that reads its own standard input is never given the
password, which would otherwise end up mixed into the data.
Run long-lived SSH jobs
Situation: A backup or migration will run longer than the agent session. The connection
may close, but you still need its state, output and exit code later.
Question: “Will this job survive the conversation?”
Job state lives on the remote disk, not in this server's memory. ssh_job_status distinguishes
running, finished and lost; ssh_job_output continues from the last byte offset; and
ssh_job_kill signals the whole process group instead of only its shell.
Transfer files to legacy routers and NAS devices
Situation: A current OpenSSH client tries SFTP, but the router or NAS only understands
the classic scp protocol. The file must still arrive intact and replace its target safely.
Question: “Can this old device still receive a verified file?”
If the device has neither sha256sum nor openssl, the result says unavailable and names
the reason instead of reporting a false match. Whole directories use recursive: true and
verify their hashes in one batch.
Destructive command protection for AI agents
The guard runs locally, before a command reaches SSH. It separates operations that can be
recovered from those that destroy the container holding the data, and it checks command order
inside chains and batches.
rm -rf /srv/app && cp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old
# REFUSED before the first command runs
The shell would delete the directory and only then discover that the backup source is gone.
The guard sees that later steps read a target already destroyed by an earlier step, so the
whole call stays on your machine. The same check catches
dropdb app && pg_dump app > backup.sql.
Refuse irreversible loss, warn about recoverable changes
Refused — the container itself
Only warned — its contents
DROP DATABASE, dropdb
DROP TABLE, TRUNCATE, DELETE FROM
docker volume rm, docker compose down -v
docker rm -f <name>
crontab -r
editing one job
mkfs, wipefs -a, lvremove, zfs destroy
chmod 777
reboot, shutdown, halt
git reset --hard
docker compose down -v is refused because -v removes named Docker volumes, including a database
volume. Without -v, stopping the services is not treated as the same irreversible action.
Recursive deletion of the filesystem root, a home directory or system trees such as /etc,
/var and /usr is also refused, including when a symlink leads there. An unresolved target
such as rm -rf "$DIR"/* is refused too: "could not check" is not treated as "safe".
Name what you stop
A command that finds its target instead of naming it is not sent. The server expands it and
answers with what stands behind the target:
bash
docker kill $(docker ps -q --filter ancestor=web)
# BLOCKED — would stop:# edge — web:latest, Up 34 days, 0.0.0.0:8443->8443/tcp
For a process the answer adds the signs that it is in use: how long it has been running,
which ports it accepts connections on, how many connections it is carrying. Named targets
cost nothing extra and go through in silence — docker kill web-1, kill 4871,
systemctl stop app.
To go ahead, name what is being stopped. The names are checked against what the command
actually reaches, so a mask that has drifted onto something else is refused rather than
confirmed:
A pattern over command lines is a case of its own. It matches the very command that carries
it, so the shell running it is signalled before the target and the reply breaks off in the
middle. Such a strike is not confirmed but rewritten — by number, or with one character
written as a class so the pattern stops matching itself:
Three outcomes stay apart: targets found, the expansion reached nothing, and nothing to ask
with — no engine on the machine, a clipped answer, a connection that failed. The last two
are refusals as well: not knowing is not a reason to proceed.
Confirm an intentional destructive command
Nothing is forbidden permanently. Add # CONFIRMED-DESTRUCTIVE to a reviewed command and it
is allowed through. When the guard refuses one entry in a batch, the complete batch stops
before execution, so the server is never left after a half-run operation.
The guard works within a single call. It cannot connect a delete in one invocation with a
read in the next, or reason about tools it does not recognize. It is a seatbelt, not a policy
engine: recoverable operations remain your call. Path restrictions and quoting rules are
documented in docs/security.md.
Tools
18 SSH MCP tools for server operations. Full parameters and examples live in
docs/tools.md.
Tool
What it does
ssh_exec
Run one command or a batch, with the destructive-command guard and optional detach
ssh_file_read
Read one or several files, text or binary
ssh_file_write
Write files with atomic rename and optional SHA-256 verification
ssh_file_list
List a directory, with optional glob and recursion
ssh_upload
Upload a file or directory over SSH, binary-safe with integrity checks; a directory replaces the target or merges into it
ssh_download
Download a file or directory over SSH, binary-safe with integrity checks
ssh_job_status
State of a background job: running, finished, or lost
ssh_job_output
Read accumulated output from a byte offset
ssh_job_list
List jobs, sweeping finished ones past their TTL
ssh_job_kill
Signal a job's whole process group
ssh_log_tail
Last N lines of one or several logs, glob supported; a container by name
ssh_log_search
Pattern search across logs, or through a container's log
ssh_snapshot
One-shot health snapshot: services, resources, Docker, network, errors
ssh_monitor
Transport control: stats, reload, test, list, close
Certificate expiry, SAN, chain and renewal hook for a domain
ssh_disk_breakdown
Where the disk went: du top-N, Docker, journald, caches
ssh_service_status
systemctl status plus a journalctl tail for one unit
MCP tool safety annotations
Standard MCP annotations tell clients which tools are read-only, destructive, idempotent or
open-world. See the full table.
Run SSH commands and manage remote files
Commands, file reads and writes, directory listings — the ordinary work on a machine, each
answer already parsed.
Monitor long-running SSH jobs
Slow work is detached and followed instead of waited for: every look says how far it got.
Search logs and check server health
Logs of files and containers, and a one-shot picture of the machine, with output capped so
a tail does not eat the context window.
Upload and download files over SSH
Binary-safe transfers with integrity checks. Details in docs/transfer.md.
For binaries and large files use ssh_upload / ssh_download — base64 chunks and
heredocs are not binary-safe or atomic.
Audit Linux servers over SSH
Read-only and batched into one round trip. Details in docs/audit.md.
Windows SSH compatibility mode
Windows uses compatibility mode automatically. When connection multiplexing is
unavailable, the server switches to one connection per command. The same tools remain
available over key-based SSH — no separate setup or Windows-specific implementation.
Put it wherever you like — next to your agent's own config is the usual choice. The examples below use ~/.claude/ssh-profiles.json; for other agents swap the directory (~/.codex/, ~/.qwen/, ~/.config/opencode/):
There is no profile the server falls back to: each one is a different machine, and a command
sent to the wrong machine is not something an error message can undo afterwards. Ask without
a name and the answer lists the names to choose from:
code
ssh_exec({ command: "uptime" })
→ No profile specified. Name one explicitly: production
A profile the server cannot use for SSH — no host, no username, or mode: "local" — is skipped without complaint, and fields it does not recognize are left alone, so the file can be shared with other tools. A profile with a broken field is a different case: it is named along with the field and the value, and its healthy neighbors keep working.
Each profile optionally takes a pathSecurity block that whitelists or blacklists the paths file tools may touch — see docs/security.md.
A profile that logs in by key but needs sudo on the far side takes a sudoPassword — the secret sudo is answered with, which on many machines is not the login password. Keep it in the secrets file rather than here.
Keep SSH passwords and passphrases out of profiles
Prefer keys. If a password or encrypted-key passphrase is unavoidable, keep it in a separate
secrets file, never in the profile itself:
sudoPassword is what sudo is answered with on that machine. A profile logging in by key
has no login password to offer, and where the two differ the login one is the wrong answer;
without it, password is used.
The secrets file must be readable only by you (chmod 600). Relative paths resolve from the
profiles file; secrets stay out of argv and are masked in logs. See
credentials security.
Configure Claude Code, Codex and other MCP clients
Choose the client you use and point it at the same profiles file.
Claude Code
One command; -s user makes the server available in every project:
bash
claude mcp add ssh -s user \
-e SSH_PROFILES_FILE="$HOME/.claude/ssh-profiles.json" \
-- npx -y @hypnosis/ssh-mcp-server
Gemini CLI, Hermes, Cline, an editor plugin or your own agent work the same way. All they
need is a command to run and one environment variable.
Restart your MCP client
Restart the client, then run ssh_monitor({ action: "list" }) to confirm the profile loaded.
SSH MCP server configuration
Variable
What it does
Default
SSH_PROFILES_FILE
Path to the profiles JSON — required
—
SSH_MCP_LOG_LEVEL
debug, info, warn, error
info
LOG_LEVEL
Fallback, used only when SSH_MCP_LOG_LEVEL is unset
info
SSH_MCP_LOG_TIMESTAMP
Timestamps in log lines
true
SSH_MCP_CONTROL_PERSIST
Seconds a shared connection stays alive after the last command; 0 closes it at once
600
SSH_MCP_CONTROL_DIR
Where control sockets live
~/.ssh/ssh-mcp
SSH_MCP_PROFILES_CACHE_TTL
Profile cache TTL, ms
60000
SSH_MCP_PROFILES_WATCH
Reload the profiles file when it changes
true
The shared connection outlives this process on purpose: closing it on exit would cut the channel another window on the same machine is using.
SSH MCP server limitations
Every limit tells you the way around it. A tool that cannot do something says so and
names ssh_exec, which runs commands on the machine directly — an unsupported log driver,
a utility the machine does not have, an engine this server does not speak. You do not have
to know in advance where the tools end: the refusal says it, at the moment it matters.
Three refusals deliberately stay silent about the shell, because there it is the wrong
answer: a path your profile forbids (walking around your own rule is not a fix), a
malformed call (the fix is in the call), and a refusal from ssh_exec itself.
Cancellation: a cancelled call now stops the command on the server too, sent as a second call over the same connection. Where the server has no /proc, the command is found through ps instead. FreeBSD is not verified: correct behaviour there is not guaranteed. File transfers and ssh_snapshot do not take cancellation at all.
Atomic writes: BSD and macOS cannot pre-check cross-filesystem renames.
SSH MCP server roadmap
Full test run against macOS SSH hosts
End-to-end compatibility run on Windows
Multi-host audits — compare health across several SSH profiles in one call
Import profiles from the existing ~/.ssh/config
Resumable transfers for large files and unstable connections
Remote operation timeline — commands, transfers and guard decisions in one audit trail
Ready-made SSH troubleshooting playbooks
Container logs without dropping to the shell — DONE:ssh_log_tail and ssh_log_search take a container name, ask docker where it writes and read that file with the same machinery as any other log
A refusal that leaves you stuck — DONE: every limit now names ssh_exec as the way through, so hitting the edge of a tool costs one sentence instead of a guessing game
Answers that reach the model — DONE: command output, matched log lines, machine names and snapshot sections travel in the fields, not only in the text
Smaller MCP tool schemas — DONE: the tool list got 10% lighter, and a detached job now shows the last lines it wrote instead of being polled blind
Long work under root — DONE: a detached job runs with sudo and is followed as root, and a key-only profile answers sudo with its own sudoPassword
Develop and test the SSH MCP server
bash
npm install
npm run build # tsc
npx tsc --noEmit # types, plus dead declarations
npm run test:unit # unit tests
npm run lab:up # start the two test containers
npm run test:live # live suite against those containers
The live suite runs against real containers — one BusyBox, one coreutils — because the two disagree quietly, and a mock agrees with whoever wrote it. See docs/architecture.md for the layout.
