{ "markdown": "# SSH MCP Server — Remote server tools for AI agents\n\n\n \n \n \n \n
\n \n \n \"SSH\n \n \n

An SSH MCP server — a multitool that saves you and your AI agent time and tokens on debugging, development and server maintenance.

\n

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.

\n
\n\nIt 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.\n\nWorks with Claude Code, Codex CLI, Cline, opencode, Gemini CLI, Qwen Code, Hermes and other MCP clients.\n\n[![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dio.github.hypnosis%2Fssh-mcp-server%26version%3Dlatest&query=%24.servers%5B0%5D.server.version&style=flat-square&logo=modelcontextprotocol&logoColor=white&label=MCP%20Registry&color=0F172A)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.hypnosis/ssh-mcp-server&version=latest) [![Glama](https://glama.ai/mcp/servers/hypnosis/ssh-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/hypnosis/ssh-mcp-server) [![Smithery](https://img.shields.io/badge/Smithery-install-EA580C?style=flat-square)](https://smithery.ai/servers/hypnosis/ssh-mcp-server) [![npm downloads](https://img.shields.io/npm/dm/@hypnosis/ssh-mcp-server?style=flat-square&logo=npm&logoColor=white&color=2EA043&label=downloads)](https://www.npmjs.com/package/@hypnosis/ssh-mcp-server) [![tests](https://img.shields.io/github/actions/workflow/status/hypnosis/ssh-mcp-server/test.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=tests)](https://github.com/hypnosis/ssh-mcp-server/actions/workflows/test.yml)\n\n**[Install](#install-in-30-seconds) · [Tools](#tools) · [Setup](#set-up-the-ssh-mcp-server) · [Security](#destructive-command-protection-for-ai-agents) · [Roadmap](#ssh-mcp-server-roadmap) · [Docs](docs/tools.md) · [Changelog](CHANGELOG.md)**\n\n---\n\n## Install in 30 seconds\n\nNo global installation required. `npx` downloads the package on first use:\n\n```bash\nnpx -y @hypnosis/ssh-mcp-server\n```\n\nAdd it to your MCP client — **Claude Code**, for example — for every project:\n\n```bash\nclaude mcp add ssh -s user \\\n -e SSH_PROFILES_FILE=\"$HOME/.claude/ssh-profiles.json\" \\\n -- npx -y @hypnosis/ssh-mcp-server\n```\n\nOr write it by hand — the same server in the config shape most clients share:\n\n```json\n{\n \"mcpServers\": {\n \"ssh\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@hypnosis/ssh-mcp-server\"],\n \"env\": {\n \"SSH_PROFILES_FILE\": \"~/.claude/ssh-profiles.json\"\n }\n }\n }\n}\n```\n\nThen create `~/.claude/ssh-profiles.json` with at least one machine:\n\n```json\n{\n \"profiles\": {\n \"production\": {\n \"host\": \"server.example.com\",\n \"username\": \"admin\",\n \"privateKeyPath\": \"~/.ssh/your_private_key\"\n }\n }\n}\n```\n\nThat is enough to connect.\n\nCodex, opencode, Qwen Code and other clients are covered in\n[Set up the SSH MCP server](#set-up-the-ssh-mcp-server).\n\n### Install as a plugin\n\nSome clients — **Claude Code**, for example — can take the whole thing as a plugin instead:\n\n```\n/plugin marketplace add hypnosis/ssh-mcp-server\n/plugin install ssh-mcp-server@ssh-mcp-server\n```\n\nThe plugin reads `~/.claude/ssh-profiles.json` unless `SSH_PROFILES_FILE` says otherwise, so\ncreate that file first and the server comes up with your machines already loaded.\n\n### Requirements\n\n[![npm version](https://img.shields.io/npm/v/@hypnosis/ssh-mcp-server?style=flat-square&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@hypnosis/ssh-mcp-server) [![Node.js](https://img.shields.io/node/v/@hypnosis/ssh-mcp-server?style=flat-square&logo=nodedotjs&logoColor=white&color=5FA04E)](https://nodejs.org/) [![TypeScript](https://img.shields.io/npm/dependency-version/@hypnosis/ssh-mcp-server/dev/typescript?style=flat-square&logo=typescript&logoColor=white&color=3178C6&label=typescript)](https://www.typescriptlang.org/) [![MCP SDK](https://img.shields.io/npm/dependency-version/@hypnosis/ssh-mcp-server/@modelcontextprotocol/sdk?style=flat-square&logo=modelcontextprotocol&logoColor=white&color=0F172A&label=MCP%20SDK)](https://modelcontextprotocol.io/)\n\n**Node.js 18+** and a system `ssh` client on `PATH`. On Windows, use a key-based profile;\npassword and passphrase profiles are not currently available.\n\nPrefer a pinned version, offline work, or one less registry check per launch:\n`npm install -g @hypnosis/ssh-mcp-server`, then use `ssh-mcp-server` as the command instead\nof `npx`.\n\n## Who this is for\n\n- **DevOps and SREs** who want faster audits, incident checks and routine server work.\n- **Vibe coders and indie builders** who ship with an AI assistant and run what they build\n on their own servers.\n- **Sysadmins and platform engineers** who want structured tools instead of an unrestricted\n raw shell.\n- **Developers and small teams running their own VPS** without a dedicated operations team.\n- **Homelab, NAS and router owners** whose useful hardware has outlived its modern protocols.\n\n## Why an SSH MCP server instead of a raw shell\n\n### Fewer tokens, lower AI costs\n\nA raw shell gives an AI agent a firehose: repeated commands, ASCII tables and log dumps.\nIt burns tokens turning that noise into a picture of the server — your money.\n\n### Faster server debugging\n\nPurpose-built tools batch routine checks, cap noisy output and return the part that matters.\nThe agent spends less time translating terminal output and gets to the fix sooner.\n\n### Less guesswork, fewer AI mistakes\n\nStructured answers say what was found, what could not be measured and what was truncated.\nThat leaves the agent less room to fill gaps with a hallucination — and gives you fewer bad\nfixes, calmer deploys and more reliable code.\n\n## SSH compatibility: modern servers, legacy gear and Windows\n\n### Use your existing OpenSSH setup\n\nNo bundled SSH implementation, no native bindings, no rebuild per platform. Commands ride the\nsystem `ssh` client, so your keys, your `~/.ssh/config`, your jump hosts and your agent\nforwarding all keep working exactly as they do in a terminal. When supported, one shared\nmultiplexed connection per destination means you authenticate once, not once per command.\n\n### SSH support for legacy servers, routers and NAS devices\n\nSend a file to a router with a modern `scp` and you get this:\n\n```bash\nscp app.conf router:/etc/\n# scp: subsystem request failed on channel 0\n```\n\nNothing is broken — a current `scp` speaks the new protocol, and the router does not know it.\nIn a terminal you now go read a forum thread and come back with an extra flag. Here you do\nnothing: the transfer is tried, the refusal is recognized, the old protocol is used instead,\nand that machine is remembered so the next file goes straight there.\n\n**Fallbacks for older SSH clients and missing tools**\n\nOld gear gets a fallback, not a dead end. When a modern feature is missing, the server takes\nthe older road where it can:\n\n| Your machine | What you get |\n|---|---|\n| A router or NAS too small for modern file transfer | The file still lands — the old protocol is used automatically |\n| A server from ten years ago | The workflow still works; it just opens a fresh connection per command instead of reusing one |\n| A stripped-down image with no way to hash a file | The upload says \"could not verify\" instead of claiming a match nobody checked |\n| A box where a tool simply is not installed | The answer says \"not measured\" — never a zero that reads as \"nothing there\" |\n\n## Built for the Model Context Protocol\n\nBuilt on the official MCP SDK, TypeScript throughout, 2500+ unit tests plus a live suite that\nruns against real containers rather than mocks.\n\n---\n\n## Raw SSH vs an SSH MCP server: the same job, both ways\n\n### SSH server health check\n\n> **Situation:** A deploy just went out. The server feels slow, and you do not know whether\n> disk, memory, services, containers or errors are to blame.\n>\n> **Question:** “Is this box healthy?”\n\n#### Raw SSH\n\n```console\n$ uptime\n 10:42:17 up 18 days, 3:21, 2 users, load average: 0.42, 0.31, 0.28\n$ df -hT\nFilesystem Type Size Used Avail Use% Mounted on\n/dev/sda1 ext4 40G 35G 5.0G 87% /\noverlay overlay 40G 35G 5.0G 87% /var/lib/docker/overlay2/...\n$ free -h\n total used free shared buff/cache available\nMem: 7.7Gi 4.9Gi 612Mi 121Mi 2.2Gi 2.5Gi\n$ systemctl --failed\n UNIT LOAD ACTIVE SUB DESCRIPTION\n● api-worker.service loaded failed failed API background worker\n$ docker ps -a\nCONTAINER ID IMAGE STATUS PORTS\n8e14d0b41c2a api:latest Up 3 minutes 0.0.0.0:8080->8080/tcp\n65b894af2430 worker:latest Exited (1) 2 minutes ago\n$ ss -tulpn\nNetid State Local Address:Port Process\ntcp LISTEN 0.0.0.0:22 users:((\"sshd\",pid=842,fd=3))\ntcp LISTEN 0.0.0.0:8080 users:((\"docker-proxy\",pid=1942,fd=4))\n$ journalctl -p err --since -1h | tail -50\nAug 20 10:39:14 prod api-worker[22104]: database connection timed out\nAug 20 10:39:14 prod systemd[1]: api-worker.service: Failed with result 'exit-code'.\n```\n\nThat is still an abridged result. A complete check needs more commands for CPU, service\nstates, container counts and recent errors, each with its own output format. Worse, a box\nwithout `ss` can look like it has zero listeners when the port check never ran.\n\n#### Structured MCP result\n\n```typescript\nssh_snapshot({ \"profile\": \"production\" })\n```\n\n```json\n{\n \"disk_pct\": 87,\n \"mem_pct\": 64,\n \"cpu_pct\": 12,\n \"load\": \"0.42 0.31 0.28\",\n \"containers\": 7,\n \"ports\": 14,\n \"services_running\": 3,\n \"recent_errors\": 21,\n \"unavailable\": []\n}\n```\n\n#### What the agent gains\n\n| Raw SSH | Structured MCP | Your gain |\n|---|---|---|\n| Several commands and ASCII tables | Named fields in one result | One call, named fields and fewer round trips |\n| A missing tool can look like empty output | `unavailable` names what was not measured | Less guessing and fewer bad fixes |\n| You sort through disks, services and errors | The problem signals are already surfaced | Faster debugging |\n\nA full `ssh_audit_baseline` result can be longer than a handful of raw command outputs —\nabout 1,077 tokens versus 765 in our lab measurement. The saving comes from the complete\nworkflow, not from making one response shorter.\n\nIn a real troubleshooting session, purpose-built tools reduced 49 separate command calls to\n4 MCP calls. Every additional call starts another model turn with the accumulated\nconversation. Prompt caching can reduce the cost of repeated input, but new commands and\ntheir output still consume context. Fewer round trips mean fewer tokens across the session,\nless repeated analysis and a faster path to the answer.\n\n**Need the whole picture rather than the pulse?** `ssh_audit_baseline` batches system, disk,\nmemory, ports, sshd, failed units, Docker, firewall and updates. Findings arrive as\n**CRITICAL / WARNING / OK**; unmeasured sections are named instead of silently reading as zero.\n\n### Linux server log search\n\n> **Situation:** The API is timing out, but the same message may be in nginx, syslog,\n> journald or an application log you cannot read with your normal user.\n>\n> **Question:** “Where did that error come from?”\n\n#### Raw SSH\n\n```console\n$ grep -i \"timeout\" /var/log/nginx/error.log\n2026/08/20 10:38:54 [error] upstream timed out while reading response header\n$ grep -i \"timeout\" /var/log/syslog\nAug 20 10:39:14 prod api-worker[22104]: database connection timed out\n$ grep -i \"timeout\" /var/log/app/*.log 2>/dev/null\n$ journalctl -u api --since \"1 hour ago\" | grep -i timeout\nAug 20 10:39:14 prod api[22104]: database connection timed out after 30000ms\n```\n\nThe third command looks clean, but `2>/dev/null` also hid a permission error. \"Nothing\nmatched\" and \"nothing was read\" now look identical. A busy log can also return thousands of\nlines and push the rest of the incident out of the agent's context.\n\n#### Structured MCP result\n\n```typescript\nssh_log_search({ \"profile\": \"production\",\n \"path\": [\"/var/log/nginx/error.log\", \"/var/log/syslog\", \"/var/log/app/*.log\"],\n \"query\": \"timeout\", \"context\": 2, \"since\": \"1h\" })\n```\n\n```json\n{\n \"matches\": 34,\n \"lines\": [\n { \"file\": \"/var/log/nginx/error.log\", \"line\": 4821,\n \"text\": \"upstream timed out while reading response header\", \"context\": false },\n { \"file\": \"/var/log/nginx/error.log\", \"line\": 4822,\n \"text\": \"client closed connection\", \"context\": true }\n ],\n \"files_searched\": 6,\n \"files_unreadable\": [\"/var/log/app/private\"],\n \"files_skipped\": 12,\n \"files_undated\": [],\n \"limited\": false,\n \"truncated\": false\n}\n```\n\n#### What the agent gains\n\n| Raw SSH | Structured MCP | Your gain |\n|---|---|---|\n| Four searches and four outputs | One search across files and globs | Fewer tokens and round trips |\n| Permission errors can disappear | `files_unreadable` names every missed path | No false \"logs are clean\" conclusion |\n| Output can grow without a useful ceiling | `limited` and `truncated` expose every cutoff | Safer decisions from partial results |\n\n`since` uses the server's clock, `namesOnly: true` returns only matching paths, and\n`ssh_log_tail` reads the last N lines from several logs in one call.\n\n### Safe remote config edits\n\n> **Situation:** You need to replace an nginx config on a live server. A dropped connection,\n> wrong mode or unchecked copy could leave the service with a broken file.\n>\n> **Question:** “Can I replace this config without leaving a partial file?”\n\n#### Raw SSH\n\n```console\n$ sudo sh -c 'cat > /etc/nginx/conf.d/api.conf' <<'EOF'\nserver {\n listen 80;\n location / { proxy_pass http://127.0.0.1:8080; }\n}\nEOF\n$ echo $?\n0\n```\n\nExit code zero says the shell finished. It does not prove which bytes landed, and `>`\ntruncated the old file before the first byte of the new one arrived. If the connection drops\nmid-write, the service is left with a partial config.\n\n#### Structured MCP result\n\n```typescript\nssh_file_write({ \"profile\": \"production\",\n \"files\": [{ \"path\": \"/etc/nginx/conf.d/api.conf\",\n \"content\": \"server {\\n listen 80;\\n location / { proxy_pass http://127.0.0.1:8080; }\\n}\\n\",\n \"mode\": \"644\", \"sudo\": true, \"verify\": true }] })\n```\n\n```json\n{\n \"files\": [{ \"path\": \"/etc/nginx/conf.d/api.conf\", \"written\": true,\n \"verified\": \"verified\", \"reason\": null, \"bytes\": 79 }]\n}\n```\n\n#### What the agent gains\n\n| Raw SSH | Structured MCP | Your gain |\n|---|---|---|\n| The target is truncated before the copy completes | A complete temp file replaces it with one rename | No half-written config |\n| Exit code only | Bytes and verification outcome are named | You know what actually landed |\n| Permissions live inside shell text | `sudo`, `mode` and `verify` are per-file fields | Predictable ownership and fewer quoting mistakes |\n\n`verified` has three honest outcomes: `verified`, `unavailable` when the server has no hash\ntool, and `skipped` when verification was not requested. For reads, `ssh_file_read` accepts a\nlist of paths; `ssh_file_list` handles globs, recursion, sizes and modes.\n\n### Run batch SSH commands with sudo\n\n> **Situation:** A deploy is ready, but nginx syntax, service state and recent errors must all\n> be checked before traffic moves. One failed check should not disappear inside a combined dump.\n>\n> **Question:** “Did every preflight check pass?”\n\n#### Raw SSH\n\n```console\n$ ssh admin@server.example.com 'sudo nginx -t'\nnginx: configuration file /etc/nginx/nginx.conf test is successful\n$ ssh admin@server.example.com 'sudo systemctl is-active nginx'\nactive\n$ ssh admin@server.example.com 'sudo tail -5 /var/log/nginx/error.log'\n2026/08/20 10:38:54 [error] upstream timed out while reading response header\n```\n\nThree connections return three unrelated outputs. If the commands are joined with `;`, the\nshell reports only the last exit code; if they are joined with `&&`, later checks disappear\nafter the first failure.\n\n#### Structured MCP result\n\n```typescript\nssh_exec({ \"profile\": \"production\",\n \"command\": [\"nginx -t\", \"systemctl is-active nginx\",\n \"tail -5 /var/log/nginx/error.log\"],\n \"sudo\": true })\n```\n\n```json\n{\n \"commands\": [\n { \"command\": \"nginx -t\", \"exit_code\": 0, \"truncated\": false, \"clipped_bytes\": 0,\n \"stdout\": \"\", \"stderr\": \"nginx: configuration file /etc/nginx/nginx.conf test is successful\\n\" },\n { \"command\": \"systemctl is-active nginx\", \"exit_code\": 0, \"truncated\": false,\n \"clipped_bytes\": 0, \"stdout\": \"active\\n\", \"stderr\": \"\" },\n { \"command\": \"tail -5 /var/log/nginx/error.log\", \"exit_code\": 0, \"truncated\": false,\n \"clipped_bytes\": 0, \"stdout\": \"2026/08/21 09:14:02 [error] upstream timed out\\n\", \"stderr\": \"\" }\n ],\n \"job_id\": null\n}\n```\n\n#### What the agent gains\n\n| Raw SSH | Structured MCP | Your gain |\n|---|---|---|\n| Three calls and unrelated outputs | One ordered command list | Fewer round trips |\n| A combined shell can hide intermediate status | Every command keeps its own `exit_code` | No missed failed check |\n| `sudo` and quoting are repeated in command text | `sudo` applies to the whole batch | Fewer quoting mistakes |\n\nThe destructive-command guard checks the complete list before the first command runs. If one\nentry is refused, every other entry is marked as not run and nothing is sent to the server.\n\nEach command carries its own `stdout` and `stderr`. A command that ran and printed nothing\nhas an empty string; a command that never ran has no such field at all, so the two cannot be\nconfused. Output over 128 KB per command keeps both ends — the head for tables, the tail for\nlogs — with a seam in between naming the amount, and `clipped_bytes` says how much was cut.\nCutting happens on byte boundaries and steps back to the edge of a character, so a clipped\nanswer never carries a replacement mark.\n\n`sudo` reaches the server without a terminal: the profile's answer is handed to `sudo` on\nstandard input. Which secret that is comes from `sudoPassword` when the profile names one and\nfrom `password` otherwise — a profile that logs in by key has no login password at all, and\nwhere a machine keeps the two apart the login one is the wrong answer. Where there is nothing\nto answer with, the reply says so and names the ways out, instead of leaving sudo's own advice\nabout `-S` and askpass helpers. A command that reads its own standard input is never given the\npassword, which would otherwise end up mixed into the data.\n\n### Run long-lived SSH jobs\n\n> **Situation:** A backup or migration will run longer than the agent session. The connection\n> may close, but you still need its state, output and exit code later.\n>\n> **Question:** “Will this job survive the conversation?”\n\n#### Raw SSH\n\n```console\n$ ssh admin@server.example.com 'pg_dump app | gzip > /srv/backups/app.sql.gz'\nclient_loop: send disconnect: Broken pipe\n```\n\nThe terminal is gone. You now have to reconnect, find the process, inspect the target file\nand guess whether the backup finished or stopped halfway.\n\n#### Structured MCP result\n\n```typescript\nssh_exec({ \"profile\": \"production\",\n \"command\": \"pg_dump app | gzip > /srv/backups/app.sql.gz\",\n \"detach\": true })\n```\n\n```json\n{\n \"commands\": [{\n \"command\": \"pg_dump app | gzip > /srv/backups/app.sql.gz\",\n \"exit_code\": null,\n \"truncated\": false,\n \"timed_out\": false,\n \"blocked\": false,\n \"blocked_reason\": null,\n \"not_run\": false,\n \"warning\": null\n }],\n \"job_id\": \"mst0f2q1-9ab3c4d5\"\n}\n```\n\n#### What the agent gains\n\n| Raw SSH | Structured MCP | Your gain |\n|---|---|---|\n| The job is tied to one SSH session | The remote job has a persistent id | Safe disconnects and restarts |\n| Reconnecting means searching processes and files | Status and exit code have named states | No guessing whether it finished |\n| Reading output again repeats old text | Output continues from a byte offset | Lower token use on long jobs |\n\nJob state lives on the remote disk, not in this server's memory. `ssh_job_status` distinguishes\n`running`, `finished` and `lost`; `ssh_job_output` continues from the last byte offset; and\n`ssh_job_kill` signals the whole process group instead of only its shell.\n\n### Transfer files to legacy routers and NAS devices\n\n> **Situation:** A current OpenSSH client tries SFTP, but the router or NAS only understands\n> the classic scp protocol. The file must still arrive intact and replace its target safely.\n>\n> **Question:** “Can this old device still receive a verified file?”\n\n#### Raw SSH\n\n```console\n$ scp app.conf operator@router:/etc/app.conf\nsubsystem request failed on channel 0\nscp: Connection closed\n```\n\nThe usual next step is to remember the legacy flag, retry the copy and then run a separate\nhash command—if the device has a hash tool at all.\n\n#### Structured MCP result\n\n```typescript\nssh_upload({ \"profile\": \"router\", \"local_path\": \"./app.conf\",\n \"remote_path\": \"/etc/app.conf\", \"sudo\": true,\n \"mode\": \"644\", \"owner\": \"root:root\", \"verify\": true })\n```\n\n```json\n{\n \"files\": [{\n \"path\": \"/etc/app.conf\",\n \"written\": true,\n \"verified\": \"verified\",\n \"reason\": null,\n \"bytes\": 1284\n }]\n}\n```\n\n#### What the agent gains\n\n| Raw SSH | Structured MCP | Your gain |\n|---|---|---|\n| Modern SFTP mode stops at the first error | Classic scp fallback is automatic and remembered | Old gear still works |\n| A successful copy does not prove integrity | SHA-256 verification has a named outcome | Corruption is not mistaken for success |\n| Direct replacement can leave a partial target | A temp file is moved into place after transfer | The working file survives interruptions |\n\nIf the device has neither `sha256sum` nor `openssl`, the result says `unavailable` and names\nthe reason instead of reporting a false match. Whole directories use `recursive: true` and\nverify their hashes in one batch.\n\n## Destructive command protection for AI agents\n\nThe guard runs locally, before a command reaches SSH. It separates operations that can be\nrecovered from those that destroy the container holding the data, and it checks command order\ninside chains and batches.\n\n### Stop a destructive chain before it starts\n\nA safe backup-and-replace sequence:\n\n```bash\ncp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old && rm -rf /srv/app\n```\n\nThe same operations in the wrong order:\n\n```bash\nrm -rf /srv/app && cp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old\n# REFUSED before the first command runs\n```\n\nThe shell would delete the directory and only then discover that the backup source is gone.\nThe guard sees that later steps read a target already destroyed by an earlier step, so the\nwhole call stays on your machine. The same check catches\n`dropdb app && pg_dump app > backup.sql`.\n\n### Refuse irreversible loss, warn about recoverable changes\n\n| Refused — the container itself | Only warned — its contents |\n|---|---|\n| `DROP DATABASE`, `dropdb` | `DROP TABLE`, `TRUNCATE`, `DELETE FROM` |\n| `docker volume rm`, `docker compose down -v` | `docker rm -f ` |\n| `crontab -r` | editing one job |\n| `mkfs`, `wipefs -a`, `lvremove`, `zfs destroy` | `chmod 777` |\n| `reboot`, `shutdown`, `halt` | `git reset --hard` |\n\n`docker compose down -v` is refused because `-v` removes named Docker volumes, including a database\nvolume. Without `-v`, stopping the services is not treated as the same irreversible action.\n\nRecursive deletion of the filesystem root, a home directory or system trees such as `/etc`,\n`/var` and `/usr` is also refused, including when a symlink leads there. An unresolved target\nsuch as `rm -rf \"$DIR\"/*` is refused too: \"could not check\" is not treated as \"safe\".\n\n### Name what you stop\n\nA command that finds its target instead of naming it is not sent. The server expands it and\nanswers with what stands behind the target:\n\n```bash\ndocker kill $(docker ps -q --filter ancestor=web)\n# BLOCKED — would stop:\n# edge — web:latest, Up 34 days, 0.0.0.0:8443->8443/tcp\n```\n\nFor a process the answer adds the signs that it is in use: how long it has been running,\nwhich ports it accepts connections on, how many connections it is carrying. Named targets\ncost nothing extra and go through in silence — `docker kill web-1`, `kill 4871`,\n`systemctl stop app`.\n\nTo go ahead, name what is being stopped. The names are checked against what the command\nactually reaches, so a mask that has drifted onto something else is refused rather than\nconfirmed:\n\n```bash\ndocker kill $(docker ps -q --filter ancestor=web) # CONFIRMED-KILL: edge\n```\n\nA pattern over command lines is a case of its own. It matches the very command that carries\nit, so the shell running it is signalled before the target and the reply breaks off in the\nmiddle. Such a strike is not confirmed but rewritten — by number, or with one character\nwritten as a class so the pattern stops matching itself:\n\n```bash\npkill -f relay\n# BLOCKED — two ways through:\n# kill 4871\n# pkill -f '[r]elay' # CONFIRMED-KILL: 4871\n```\n\nThree outcomes stay apart: targets found, the expansion reached nothing, and nothing to ask\nwith — no engine on the machine, a clipped answer, a connection that failed. The last two\nare refusals as well: not knowing is not a reason to proceed.\n\n### Confirm an intentional destructive command\n\nNothing is forbidden permanently. Add `# CONFIRMED-DESTRUCTIVE` to a reviewed command and it\nis allowed through. When the guard refuses one entry in a batch, the complete batch stops\nbefore execution, so the server is never left after a half-run operation.\n\nThe guard works within a single call. It cannot connect a delete in one invocation with a\nread in the next, or reason about tools it does not recognize. It is a seatbelt, not a policy\nengine: recoverable operations remain your call. Path restrictions and quoting rules are\ndocumented in **[docs/security.md](docs/security.md)**.\n\n## Tools\n\n18 SSH MCP tools for server operations. Full parameters and examples live in\n**[docs/tools.md](docs/tools.md)**.\n\n| Tool | What it does |\n|---|---|\n| `ssh_exec` | Run one command or a batch, with the destructive-command guard and optional detach |\n| `ssh_file_read` | Read one or several files, text or binary |\n| `ssh_file_write` | Write files with atomic rename and optional SHA-256 verification |\n| `ssh_file_list` | List a directory, with optional glob and recursion |\n| `ssh_upload` | Upload a file or directory over SSH, binary-safe with integrity checks; a directory replaces the target or merges into it |\n| `ssh_download` | Download a file or directory over SSH, binary-safe with integrity checks |\n| `ssh_job_status` | State of a background job: running, finished, or lost |\n| `ssh_job_output` | Read accumulated output from a byte offset |\n| `ssh_job_list` | List jobs, sweeping finished ones past their TTL |\n| `ssh_job_kill` | Signal a job's whole process group |\n| `ssh_log_tail` | Last N lines of one or several logs, glob supported; a container by name |\n| `ssh_log_search` | Pattern search across logs, or through a container's log |\n| `ssh_snapshot` | One-shot health snapshot: services, resources, Docker, network, errors |\n| `ssh_monitor` | Transport control: stats, reload, test, list, close |\n| `ssh_audit_baseline` | System, disk, memory, network, ssh, services, Docker, firewall, updates |\n| `ssh_tls_check` | Certificate expiry, SAN, chain and renewal hook for a domain |\n| `ssh_disk_breakdown` | Where the disk went: `du` top-N, Docker, journald, caches |\n| `ssh_service_status` | `systemctl status` plus a `journalctl` tail for one unit |\n\n### MCP tool safety annotations\n\nStandard MCP annotations tell clients which tools are read-only, destructive, idempotent or\nopen-world. See the [full table](docs/tools.md#what-each-tool-declares-about-itself).\n\n### Run SSH commands and manage remote files\n\nCommands, file reads and writes, directory listings — the ordinary work on a machine, each\nanswer already parsed.\n\n### Monitor long-running SSH jobs\n\nSlow work is detached and followed instead of waited for: every look says how far it got.\n\n### Search logs and check server health\n\nLogs of files and containers, and a one-shot picture of the machine, with output capped so\na tail does not eat the context window.\n\n### Upload and download files over SSH\n\nBinary-safe transfers with integrity checks. Details in [docs/transfer.md](docs/transfer.md).\n\n> **For binaries and large files use `ssh_upload` / `ssh_download`** — base64 chunks and\n> heredocs are not binary-safe or atomic.\n\n### Audit Linux servers over SSH\n\nRead-only and batched into one round trip. Details in [docs/audit.md](docs/audit.md).\n\n### Windows SSH compatibility mode\n\nWindows uses compatibility mode automatically. When connection multiplexing is\nunavailable, the server switches to one connection per command. The same tools remain\navailable over key-based SSH — no separate setup or Windows-specific implementation.\n\nThe destructive-command guard is covered in [Destructive command protection for AI agents](#destructive-command-protection-for-ai-agents).\n\n## Set up the SSH MCP server\n\nRun the package from [Install in 30 seconds](#install-in-30-seconds) first, then create a\nprofile file.\n\n### Create SSH connection profiles\n\nPut 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/`):\n\n```json\n{\n \"profiles\": {\n \"production\": {\n \"host\": \"server.example.com\",\n \"username\": \"admin\",\n \"port\": 22,\n \"privateKeyPath\": \"~/.ssh/your_private_key\"\n }\n }\n}\n```\n\n**Choose an SSH profile explicitly**\n\nThere is no profile the server falls back to: each one is a different machine, and a command\nsent to the wrong machine is not something an error message can undo afterwards. Ask without\na name and the answer lists the names to choose from:\n\n```\nssh_exec({ command: \"uptime\" })\n→ No profile specified. Name one explicitly: production\n```\n\nA 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.\n\nEach profile optionally takes a `pathSecurity` block that whitelists or blacklists the paths file tools may touch — see [docs/security.md](docs/security.md#path-security).\n\nA 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.\n\n### Keep SSH passwords and passphrases out of profiles\n\nPrefer keys. If a password or encrypted-key passphrase is unavoidable, keep it in a separate\nsecrets file, never in the profile itself:\n\n```json\n{\n \"secretsFile\": \"~/.config/ssh-mcp/secrets.json\",\n \"profiles\": {\n \"production\": {\n \"host\": \"server.example.com\",\n \"username\": \"admin\"\n }\n }\n}\n```\n\nThe secrets file is keyed by profile name — see [secrets.json.example](secrets.json.example):\n\n```json\n{\n \"production\": { \"password\": \"...\" },\n \"buildbox\": { \"sudoPassword\": \"...\" }\n}\n```\n\n`sudoPassword` is what `sudo` is answered with on that machine. A profile logging in by key\nhas no login password to offer, and where the two differ the login one is the wrong answer;\nwithout it, `password` is used.\n\nThe secrets file must be readable only by you (`chmod 600`). Relative paths resolve from the\nprofiles file; secrets stay out of `argv` and are masked in logs. See\n[credentials security](docs/security.md#credentials-keep-the-secret-out-of-the-profiles-file).\n\n### Configure Claude Code, Codex and other MCP clients\n\nChoose the client you use and point it at the same profiles file.\n\n**Claude Code**\n\nOne command; `-s user` makes the server available in every project:\n\n```bash\nclaude mcp add ssh -s user \\\n -e SSH_PROFILES_FILE=\"$HOME/.claude/ssh-profiles.json\" \\\n -- npx -y @hypnosis/ssh-mcp-server\n```\n\n**Codex CLI**\n\n```bash\ncodex mcp add ssh \\\n --env SSH_PROFILES_FILE=\"$HOME/.codex/ssh-profiles.json\" \\\n -- npx -y @hypnosis/ssh-mcp-server\n```\n\n**opencode**\n\nPut it in `~/.config/opencode/opencode.json`:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"ssh\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"-y\", \"@hypnosis/ssh-mcp-server\"],\n \"enabled\": true,\n \"environment\": {\n \"SSH_PROFILES_FILE\": \"~/.config/opencode/ssh-profiles.json\"\n }\n }\n }\n}\n```\n\n**Qwen Code**\n\nOne command, same as the others:\n\n```bash\nqwen mcp add ssh \\\n -e SSH_PROFILES_FILE=\"$HOME/.qwen/ssh-profiles.json\" \\\n npx -y @hypnosis/ssh-mcp-server\n```\n\n**Other MCP clients**\n\nGemini CLI, Hermes, Cline, an editor plugin or your own agent work the same way. All they\nneed is a command to run and one environment variable.\n\n### Restart your MCP client\n\nRestart the client, then run `ssh_monitor({ action: \"list\" })` to confirm the profile loaded.\n\n## SSH MCP server configuration\n\n| Variable | What it does | Default |\n|---|---|---|\n| `SSH_PROFILES_FILE` | Path to the profiles JSON — **required** | — |\n| `SSH_MCP_LOG_LEVEL` | `debug`, `info`, `warn`, `error` | `info` |\n| `LOG_LEVEL` | Fallback, used only when `SSH_MCP_LOG_LEVEL` is unset | `info` |\n| `SSH_MCP_LOG_TIMESTAMP` | Timestamps in log lines | `true` |\n| `SSH_MCP_CONTROL_PERSIST` | Seconds a shared connection stays alive after the last command; `0` closes it at once | `600` |\n| `SSH_MCP_CONTROL_DIR` | Where control sockets live | `~/.ssh/ssh-mcp` |\n| `SSH_MCP_PROFILES_CACHE_TTL` | Profile cache TTL, ms | `60000` |\n| `SSH_MCP_PROFILES_WATCH` | Reload the profiles file when it changes | `true` |\n\nThe shared connection outlives this process on purpose: closing it on exit would cut the channel another window on the same machine is using.\n\n## SSH MCP server limitations\n\n**Every limit tells you the way around it.** A tool that cannot do something says so and\nnames `ssh_exec`, which runs commands on the machine directly — an unsupported log driver,\na utility the machine does not have, an engine this server does not speak. You do not have\nto know in advance where the tools end: the refusal says it, at the moment it matters.\n\nThree refusals deliberately stay silent about the shell, because there it is the wrong\nanswer: a path your profile forbids (walking around your own rule is not a fix), a\nmalformed call (the fix is in the call), and a refusal from `ssh_exec` itself.\n\n- **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.\n- **Atomic writes:** BSD and macOS cannot pre-check cross-filesystem renames.\n\n## SSH MCP server roadmap\n\n- [ ] Full test run against macOS SSH hosts\n- [ ] End-to-end compatibility run on Windows\n- [ ] Multi-host audits — compare health across several SSH profiles in one call\n- [ ] Import profiles from the existing `~/.ssh/config`\n- [ ] Resumable transfers for large files and unstable connections\n- [ ] Remote operation timeline — commands, transfers and guard decisions in one audit trail\n- [ ] Ready-made SSH troubleshooting playbooks\n\n- [x] ~~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\n- [x] ~~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\n- [x] ~~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\n- [x] ~~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\n- [x] ~~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`\n\n## Develop and test the SSH MCP server\n\n```bash\nnpm install\nnpm run build # tsc\nnpx tsc --noEmit # types, plus dead declarations\nnpm run test:unit # unit tests\nnpm run lab:up # start the two test containers\nnpm run test:live # live suite against those containers\n```\n\nThe 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](docs/architecture.md) for the layout.\n\n## Like SSH MCP Server? ⭐\n\nIf you like the tool, [give it a star on GitHub](https://github.com/hypnosis/ssh-mcp-server) — it helps more people discover the project.\n\n## Contribute to the SSH MCP server\n\nIssues and pull requests are welcome at [github.com/hypnosis/ssh-mcp-server](https://github.com/hypnosis/ssh-mcp-server).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n", "bytes": 37973, "sha": "91940086d4bceb06713dbc79020dc0314eb6733a264eea0e626c8d241d22fa79", "repo_slug": "hypnosis/ssh-mcp-server", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_hypnosis_ssh_mcp_server_db7b970b/readme" }