Skip to content
Back to search

jms-ssh-mcp

MCP server for SSH bastions that want password + TOTP and a menu-driven asset pick (JumpServer / KoKo): persistent shell per host, plain JSON, bounded replies

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/digyear/jms-ssh-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/digyear/jms-ssh-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/digyear--jms-ssh-mcp/badge.svg)](/listings/digyear--jms-ssh-mcp)

HTML

<a href="/listings/digyear--jms-ssh-mcp"><img src="/api/listings/digyear--jms-ssh-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Node 20+. Three ways, all of them stdio — there is nothing to host.

npx, no clone

npx -y jms-ssh-mcp --help

The same command also runs the current main branch without any registry involved:

npx -y github:digyear/jms-ssh-mcp --help

Client configuration

Any client that speaks MCP over stdio, mcphub and Claude Desktop included:

{
  "mcpServers": {
    "jms-ssh-mcp": {
      "command": "npx",
      "args": ["-y", "jms-ssh-mcp"],
      "env": {
        "JMS_SSH_HOST": "bastion.example.com",
        "JMS_SSH_PORT": "2222",
        "JMS_SSH_USERNAME": "alice",
        "JMS_SSH_PASSWORD": "<password>",
        "JMS_SSH_OTP_SECRET": "<base32 seed>"
      }
    }
  }
}

Use `["-y", "github:digyear/jms-ssh-mcp"]` to track main instead of a release. If you would rather not put the secrets in the client's config, point at environment variables instead:

"env": { "JMS_SSH_HOST": "...", "JMS_SSH_USERNAME": "...",
         "JMS_SSH_PASSWORD_ENV": "BASTION_PASSWORD",
         "JMS_SSH_OTP_SECRET_ENV": "BASTION_OTP_SECRET" }

Every other setting — timeouts, byte caps, the command allowlist, the host whitelist, the audit log — is an environment variable too, listed above.

Global install

npm install -g jms-ssh-mcp

then use `"command": "jms-ssh-mcp"` in the client config.

From source

git clone https://github.com/digyear/jms-ssh-mcp.git
cd jms-ssh-mcp
npm install
node src/index.js --help

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 307 lines
  1. # jms-ssh-mcp
  2. [![npm](https://img.shields.io/npm/v/jms-ssh-mcp.svg)](https://www.npmjs.com/package/jms-ssh-mcp)
  3. An MCP server for SSH bastions that do more than SSH: **password + TOTP**, then a **menu** where you pick a host, then a **persistent shell** on that host.
  4. The agent's whole interface is *host + command*. Connections, menu navigation, OTP and re-login happen inside the server, keyed by host.
  5. ```
  6. jms_ssh_run("10.0.0.15", "journalctl -n 200 --no-pager")
  7. → { "host": "10.0.0.15", "exitCode": 0, "output": "…" }
  8. ```
  9. JumpServer (KoKo) is the reference target, but any bastion with a line-oriented menu works.
  10. ## Why another SSH MCP
  11. Generic SSH MCP servers assume the connection is the destination: connect, run, disconnect. Behind a bastion that model breaks in three places, and none of them is a prompt-engineering problem:
  12. | Reality | What generic servers do | What this one does |
  13. |---|---|---|
  14. | Second factor after the password | answer `keyboard-interactive` with the password or an empty string → the handshake hangs until timeout | classifies the prompt (`otp`, `one-time code`, `verification code`, `token` …) and computes TOTP at submit time |
  15. | A menu owns stdin | `exec_command` is answered by the bastion locally, commands never reach the host | opens an interactive shell channel (`shell()`), not exec |
  16. | Re-login costs an OTP round | connect per command | one login per host, many commands, closed on purpose |
  17. Four details that cost real debugging time and are encoded here:
  18. - **KoKo submits on `\r`, never `\n`.** With LF the menu echoes the digits and swallows them; nothing is selected and every later command lands in the menu.
  19. - **The menu renders before you type at it.** The answer waits for the menu text, not for a fixed sleep, and the wait must not clear what was already buffered.
  20. - **Menu options 1–11 are commands** (`2` = search, `9` = language), so a small asset id is consumed by the menu instead of selecting the asset.
  21. - **A search result is answered with row numbers**, not asset ids — so a hostname matching several assets is reported as ambiguous instead of guessed.
  22. ## Tools (4)
  23. | Tool | Purpose |
  24. |---|---|
  25. | `jms_ssh_run(host, command, account?, timeoutMs?, maxBytes?)` | Run a command; returns `{host, exitCode, output}` |
  26. | `jms_ssh_hosts(filter?, limit?, scope?)` | The assets this account can reach, parsed |
  27. | `jms_ssh_connections()` | Which hosts currently have a live connection |
  28. | `jms_ssh_close(host?)` | Close one host, or all |
  29. `host` accepts an asset id, IP or hostname; every spelling of the same asset reuses one connection, and no tool ever asks for a session id.
  30. Logs are read with `jms_ssh_run` — there is no separate log tool, because it would only duplicate what the shell already does:
  31. ```
  32. jms_ssh_run(host, "tail -n 200 /var/log/messages")
  33. jms_ssh_run(host, "journalctl -u myapp -n 500 --no-pager --since '2 hours ago'")
  34. jms_ssh_run(host, "tail -n 5000 /var/log/app.log | grep -E 'ERROR|timeout'")
  35. ```
  36. Trimming on the target (`-n`, `--since`, `grep`) is what keeps both the transfer and the buffer small.
  37. ### Direct asset login skips the menu entirely
  38. JumpServer accepts `<login>@<system user>@<asset>` as the SSH username and drops
  39. you straight onto the target shell — no menu, no asset search, no row numbers:
  40. ```
  41. jms_ssh_run("10.0.0.15", "hostname", account: "root")
  42. → connects as alice@root@10.0.0.15, lands on [root@web-01 ~]# in 1.4 s
  43. ```
  44. Everything the menu path has to work around (waiting for menu text, CR submits,
  45. option digits that collide with asset ids, search-result row numbers) simply does
  46. not exist on this path. It is used whenever `account` is given; omit it and the
  47. server falls back to the menu, which is still the only way in when the account is
  48. not permitted to pick its own system user. A wrong account fails with the
  49. bastion's own words ("no such user: nosuchuser").
  50. ### Why the exit code is real
  51. The command is fenced with a random marker that carries `$?`:
  52. ```
  53. journalctl -n 5 --no-pager
  54. printf '\n__JMS9f2c1a7b__%s\n' "$?"
  55. ```
  56. The runner waits for `__JMS9f2c1a7b__0` and splits output from that marker. Prompt-scraping can never tell you whether a command succeeded; this can, and it does not care what the prompt looks like on the far side of the menu.
  57. ## Memory
  58. A `journalctl` or `cat` on a busy host can emit gigabytes, so the shell buffer is a **bounded window** (`JMS_SSH_MAX_BUFFER_CHARS`, default 4 MB): a small head, a rolling tail, and a counter of what was dropped. Output past it is discarded as it arrives, not after it is stored. The returned text is capped separately (`JMS_SSH_MAX_OUTPUT_BYTES`, default 256 KB, head + tail kept, `truncated: true` when it is cut).
  59. Three limits, all on the reply rather than on hope:
  60. | Limit | Default | What it protects |
  61. |---|---|---|
  62. | buffer per shell | 4 MB | the process |
  63. | returned output | 256 KB | the caller's context |
  64. | serialized reply | 1 MiB (`JMS_SSH_MAX_RESULT_BYTES`) | the bastion host: the JSON that actually crosses the transport, *after* escaping |
  65. The last one matters because escaping is not free: a NUL byte becomes six bytes of JSON, so a binary file read as text could inflate a reply by an order of magnitude. Control characters no log needs are stripped, and output that is mostly binary is reported as `binary: true` instead of being handed over.
  66. Measured: 400 000 log lines (~56 MB) → 5.8 s, 262 KB returned, buffer held 4.19 MB, dropped 52.4 MB, process RSS 90 → 156 → 90 MB. A 500 MB `cat` peaks at 195 MB RSS and returns 0.2 KB (`binary: true`).
  67. If a command outlives its timeout it is interrupted with Ctrl-C and the shell is returned to its prompt, so the next `jms_ssh_run` on that host is not queued behind a command that never ends.
  68. ## Connections
  69. - **One login per host.** A later call costs one round-trip (~0.2 s) instead of a login (~1.5 s).
  70. - **Concurrent calls collapse.** Two callers asking for the same host at the same instant share one in-flight login instead of racing two OTP rounds.
  71. - **One command at a time per host.** A single shell means a single stdin: calls against one connection are queued so two commands cannot interleave.
  72. - **Different hosts are different connections**, capped by `JMS_SSH_MAX_SESSIONS` (default 8, least recently used evicted).
  73. - **Drops heal.** A dead socket reconnects once and retries; `exit` on the target (back to the bastion prompt without dropping SSH) is detected and the asset is re-entered on the next call.
  74. - **Idle reaping is off by default** (`JMS_SSH_IDLE_TIMEOUT_MS=0`): every re-login burns an OTP, so dropping an idle shell is a cost, not hygiene. Keepalives every 15 s surface a dead link instead of hanging.
  75. ## Configuration
  76. Everything is reachable from the environment, because a container platform
  77. (mcphub and friends) gives you an env block and nowhere to put a file. A config
  78. file is optional and only useful when you have several bastions.
  79. ```bash
  80. export JMS_SSH_HOST=jumpserver.example.com
  81. export JMS_SSH_PORT=2222
  82. export JMS_SSH_USERNAME=alice
  83. export JMS_SSH_PASSWORD=... # or JMS_SSH_PASSWORD_ENV=MY_SECRET_VAR
  84. export JMS_SSH_OTP_SECRET=JBSWY3DPEHPK3PXP # base32 seed; or JMS_SSH_OTP_SECRET_ENV=...
  85. export JMS_SSH_ACCOUNT=root # optional: log in directly as alice@root@asset
  86. ```
  87. Env wins over the file for the same key; keys the env does not mention keep the
  88. file value.
  89. ### Bastion
  90. | Variable | Default | Note |
  91. |---|---|---|
  92. | `JMS_SSH_HOST` | — | required |
  93. | `JMS_SSH_PORT` | `2222` | |
  94. | `JMS_SSH_USERNAME` | — | required |
  95. | `JMS_SSH_PASSWORD` | — | or `JMS_SSH_PASSWORD_ENV` naming another variable |
  96. | `JMS_SSH_PASSWORD_ENV` | — | keeps the secret out of the process env block |
  97. | `JMS_SSH_OTP_SECRET` | — | base32 seed or a whole `otpauth://` URI |
  98. | `JMS_SSH_OTP_SECRET_ENV` | — | as above, by reference |
  99. | `JMS_SSH_ACCOUNT` | — | default system user for every `jms_ssh_run`; a per-call `account` wins |
  100. | `JMS_SSH_PRIVATE_KEY_PATH` | — | key auth instead of a password |
  101. | `JMS_SSH_PASSPHRASE` | — | for an encrypted key |
  102. | `JMS_SSH_MENU_PROMPT` | `Opt>\s*$` | the bastion's menu prompt |
  103. | `JMS_SSH_LIST_PROMPT` | `\[(Host\|Node\|Asset\|…)\]>\s*$` | prompt of the paged asset list |
  104. | `JMS_SSH_SHELL_PROMPT` | `[#$]\s*$` | prompt on the target host |
  105. | `JMS_SSH_ENTER_KEY` | `cr` | `cr`, `lf`, or a char code; KoKo needs `cr` |
  106. | `JMS_SSH_MCP_CONFIG` | — | path to a multi-bastion file instead of the keys above |
  107. ### Behaviour
  108. | Variable | Default | Note |
  109. |---|---|---|
  110. | `JMS_SSH_COMMAND_TIMEOUT_MS` | `30000` | per command |
  111. | `JMS_SSH_CONNECT_TIMEOUT_MS` | `20000` | login + menu navigation |
  112. | `JMS_SSH_IDLE_TIMEOUT_MS` | `0` | 0 = keep connections until closed |
  113. | `JMS_SSH_KEEPALIVE_MS` | `15000` | surfaces a dead link instead of hanging |
  114. | `JMS_SSH_RECONNECT` | on | `0` disables the one automatic retry |
  115. | `JMS_SSH_MENU_OPTION_MAX` | `11` | highest number the menu itself owns |
  116. | `JMS_SSH_MAX_SESSIONS` | `8` | concurrent host connections, LRU eviction |
  117. | `JMS_SSH_MAX_OUTPUT_BYTES` | `262144` | what the tool returns |
  118. | `JMS_SSH_MAX_RESULT_BYTES` | `1048576` | cap on the serialized JSON reply |
  119. | `JMS_SSH_MAX_BUFFER_CHARS` | `4194304` | what the process holds per shell |
  120. | `JMS_SSH_DEBUG` | off | prompt and timing lines on stderr |
  121. ### Guard and audit
  122. | Variable | Default | Note |
  123. |---|---|---|
  124. | `JMS_SSH_ALLOW_ALL` | off | disable the read-only allowlist |
  125. | `JMS_SSH_ALLOWED_COMMANDS` | read-only set | comma-separated names or regexes |
  126. | `JMS_SSH_ALLOWED_PREFIXES` | `sudo journalctl`, `docker logs`, `kubectl get`, … | comma-separated prefixes |
  127. | `JMS_SSH_AUDIT_LOG` | unset | JSONL trail of every attempt, refusals included |
  128. | `JMS_SSH_AUDIT_OUTPUT` | off | include the output text in the trail |
  129. The seed is the `secret=` value of the authenticator QR: `otpauth://totp/JumpServer:alice?secret=JBSWY3DPEHPK3PXP`. [`src/totp.js`](src/totp.js) parses that URI, so pasting the whole URL works too.
  130. `jms_ssh_hosts` always needs the menu, so when a default `account` sends
  131. `jms_ssh_run` straight to the target, the first listing opens a second
  132. connection in the background (one extra login, then reused).
  133. ## Security
  134. - **Read-only by default.** `jms_ssh_run` checks every pipe segment against an allowlist (`cat`, `tail`, `journalctl`, `grep`, `df`, `ps`, `docker logs`, `kubectl logs` …); `rm`, editors and shells are refused.
  135. - **No second command behind the first.** `;`, `&&`, `||`, backticks, `$(` and redirection are refused while the allowlist is on — `hostname; id` used to pass a first-word check and run as root. `|` is allowed, and each segment is validated on its own. `2>&1` and `2>/dev/null` pass.
  136. - **Prefix rules are not wildcards.** `sudo journalctl` is allowed, bare `sudo` is not.
  137. - `JMS_SSH_ALLOW_ALL=1` turns the guard off — only for a bastion account that is itself restricted.
  138. - **Secrets never travel in tool arguments.** They come from env vars or the config file; results and errors are redacted.
  139. - **The bastion is the real boundary.** An account that can log in as root on the target can do root things; scope the bastion account to the hosts it should see.
  140. - **Audit exists twice.** JumpServer records the session; the server can write its own structured trail.
  141. ## Audit log
  142. Point `JMS_SSH_AUDIT_LOG` at a file and every command attempt appends one JSON line — refusals included, because "who tried what" is the interesting half:
  143. ```bash
  144. export JMS_SSH_AUDIT_LOG=/var/log/jms-mcp/audit.jsonl
  145. ```
  146. ```json
  147. {"ts":"2026-11-20T09:57:36.395Z","pid":1234,"client":"hermes-desktop","host":"10.0.0.15","command":"hostname","outcome":"ok","exitCode":0,"ms":1154,"outputBytes":11}
  148. {"ts":"2026-11-20T09:57:37.707Z","pid":1234,"client":"hermes-desktop","host":"10.0.0.15","command":"hostname; id","outcome":"refused","reason":"Shell control operators are not allowed…","ms":0}
  149. ```
  150. - Written where the tool runs, not by the client, so a client that forgets cannot skip it.
  151. - Output text is **not** recorded, only its size: logs contain secrets more often than anyone expects. `JMS_SSH_AUDIT_OUTPUT=1` opts in.
  152. - `client` is the MCP client's own `clientInfo`, so several agents can share one file.
  153. - Append-only, 0600, one write per call. Rotate with logrotate; nothing is re-read.
  154. ## How this compares
  155. | Project | Shape | What we took |
  156. |---|---|---|
  157. | [classfang/ssh-mcp-server](https://github.com/classfang/ssh-mcp-server) (~1k★) | 6 tools: execute/upload/download/read-file/write-file/list-servers; `exec` mode with SFTP and `shell` mode with a persistent shell and command queue | the allowlist hardening: control operators refused, pipes validated per segment |
  158. | [uarlouski/ssh-mcp-server](https://github.com/uarlouski/ssh-mcp-server) | production-leaning: command+argument whitelist, SFTP, JSONL audit log, imports `~/.ssh/config`, command aliases | audit log is the next thing worth adding |
  159. | [hypnosis/ssh-mcp-server](https://github.com/hypnosis/ssh-mcp-server) | 18 purpose-built tools (jobs, log_tail, log_search, snapshot, audit baseline, TLS check) and structured answers that state what was truncated | the "say what you could not measure" habit; a job model for long commands |
  160. | [Shadow-linux/jumpserver_ssh_mcp](https://github.com/Shadow-linux/jumpserver_ssh_mcp) | JumpServer gateways with per-entrance adapters, `file_push`/`file_pull` over Koko SFTP | confirms that per-entrance adapters are the hard part, not SSH itself |
  161. | [lanchenglin/jumpserver-mcp](https://github.com/lanchenglin/jumpserver-mcp) | JumpServer REST API tools generated from `swagger.json`, plus SSH/SFTP using `{gateway_user}@{system_user}@{asset_ip}` | the direct-login username format above |
  162. The one thing none of them solve is the menu itself — they either assume direct
  163. SSH or go through JumpServer's API. Keeping both login paths is what makes this
  164. server usable on a locked-down bastion *and* fast where direct login is allowed.
  165. ## Install
  166. Node 20+. Three ways, all of them stdio — there is nothing to host.
  167. ### npx, no clone
  168. ```bash
  169. npx -y jms-ssh-mcp --help
  170. ```
  171. The same command also runs the current main branch without any registry involved:
  172. ```bash
  173. npx -y github:digyear/jms-ssh-mcp --help
  174. ```
  175. ### Client configuration
  176. Any client that speaks MCP over stdio, mcphub and Claude Desktop included:
  177. ```json
  178. {
  179. "mcpServers": {
  180. "jms-ssh-mcp": {
  181. "command": "npx",
  182. "args": ["-y", "jms-ssh-mcp"],
  183. "env": {
  184. "JMS_SSH_HOST": "bastion.example.com",
  185. "JMS_SSH_PORT": "2222",
  186. "JMS_SSH_USERNAME": "alice",
  187. "JMS_SSH_PASSWORD": "<password>",
  188. "JMS_SSH_OTP_SECRET": "<base32 seed>"
  189. }
  190. }
  191. }
  192. }
  193. ```
  194. Use `["-y", "github:digyear/jms-ssh-mcp"]` to track main instead of a release. If
  195. you would rather not put the secrets in the client's config, point at environment
  196. variables instead:
  197. ```json
  198. "env": { "JMS_SSH_HOST": "...", "JMS_SSH_USERNAME": "...",
  199. "JMS_SSH_PASSWORD_ENV": "BASTION_PASSWORD",
  200. "JMS_SSH_OTP_SECRET_ENV": "BASTION_OTP_SECRET" }
  201. ```
  202. Every other setting — timeouts, byte caps, the command allowlist, the host
  203. whitelist, the audit log — is an environment variable too, listed above.
  204. ### Global install
  205. ```bash
  206. npm install -g jms-ssh-mcp
  207. ```
  208. then use `"command": "jms-ssh-mcp"` in the client config.
  209. ### From source
  210. ```bash
  211. git clone https://github.com/digyear/jms-ssh-mcp.git
  212. cd jms-ssh-mcp
  213. npm install
  214. node src/index.js --help
  215. ```
  216. ## Layout
  217. ```
  218. src/index.js MCP surface: 4 tools, host-keyed connection registry
  219. src/session.js one bastion session: TOTP login, menu/asset selection, marker-fenced exec
  220. src/window.js bounded output window (head + rolling tail + dropped counter)
  221. src/menu.js asset table and page footer parsing
  222. src/config.js env/config-file resolution, command allowlist
  223. src/totp.js RFC 6238 (no dependency)
  224. test/ TOTP vectors, menu parsing, window bounds, tool-surface contract
  225. ```
  226. `npm test` runs the unit suite offline (42 tests). A live run needs a reachable bastion:
  227. ```bash
  228. JMS_SSH_HOST=... JMS_SSH_USERNAME=... JMS_SSH_PASSWORD_ENV=... JMS_SSH_OTP_SECRET_ENV=... node src/index.js
  229. ```
  230. MIT licensed.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.