jms-ssh-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
jms-ssh-mcp
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.
The agent's whole interface is host + command. Connections, menu navigation, OTP and re-login happen inside the server, keyed by host.
jms_ssh_run("10.0.0.15", "journalctl -n 200 --no-pager")
→ { "host": "10.0.0.15", "exitCode": 0, "output": "…" }JumpServer (KoKo) is the reference target, but any bastion with a line-oriented menu works.
Why another SSH MCP
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:
Reality | What generic servers do | What this one does |
Second factor after the password | answer | classifies the prompt ( |
A menu owns stdin |
| opens an interactive shell channel ( |
Re-login costs an OTP round | connect per command | one login per host, many commands, closed on purpose |
Four details that cost real debugging time and are encoded here:
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.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.
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.A search result is answered with row numbers, not asset ids — so a hostname matching several assets is reported as ambiguous instead of guessed.
Related MCP server: jumpserver-mcp
Tools (4)
Tool | Purpose |
| Run a command; returns |
| The assets this account can reach, parsed |
| Which hosts currently have a live connection |
| Close one host, or all |
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.
Logs are read with jms_ssh_run — there is no separate log tool, because it would only duplicate what the shell already does:
jms_ssh_run(host, "tail -n 200 /var/log/messages")
jms_ssh_run(host, "journalctl -u myapp -n 500 --no-pager --since '2 hours ago'")
jms_ssh_run(host, "tail -n 5000 /var/log/app.log | grep -E 'ERROR|timeout'")Trimming on the target (-n, --since, grep) is what keeps both the transfer and the buffer small.
Direct asset login skips the menu entirely
JumpServer accepts <login>@<system user>@<asset> as the SSH username and drops
you straight onto the target shell — no menu, no asset search, no row numbers:
jms_ssh_run("10.0.0.15", "hostname", account: "root")
→ connects as alice@root@10.0.0.15, lands on [root@web-01 ~]# in 1.4 sEverything the menu path has to work around (waiting for menu text, CR submits,
option digits that collide with asset ids, search-result row numbers) simply does
not exist on this path. It is used whenever account is given; omit it and the
server falls back to the menu, which is still the only way in when the account is
not permitted to pick its own system user. A wrong account fails with the
bastion's own words ("no such user: nosuchuser").
Why the exit code is real
The command is fenced with a random marker that carries $?:
journalctl -n 5 --no-pager
printf '\n__JMS9f2c1a7b__%s\n' "$?"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.
Memory
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).
Three limits, all on the reply rather than on hope:
Limit | Default | What it protects |
buffer per shell | 4 MB | the process |
returned output | 256 KB | the caller's context |
serialized reply | 1 MiB ( | the bastion host: the JSON that actually crosses the transport, after escaping |
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.
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).
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.
Connections
One login per host. A later call costs one round-trip (~0.2 s) instead of a login (~1.5 s).
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.
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.
Different hosts are different connections, capped by
JMS_SSH_MAX_SESSIONS(default 8, least recently used evicted).Drops heal. A dead socket reconnects once and retries;
exiton the target (back to the bastion prompt without dropping SSH) is detected and the asset is re-entered on the next call.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.
Configuration
Everything is reachable from the environment, because a container platform (mcphub and friends) gives you an env block and nowhere to put a file. A config file is optional and only useful when you have several bastions.
export JMS_SSH_HOST=jumpserver.example.com
export JMS_SSH_PORT=2222
export JMS_SSH_USERNAME=alice
export JMS_SSH_PASSWORD=... # or JMS_SSH_PASSWORD_ENV=MY_SECRET_VAR
export JMS_SSH_OTP_SECRET=JBSWY3DPEHPK3PXP # base32 seed; or JMS_SSH_OTP_SECRET_ENV=...
export JMS_SSH_ACCOUNT=root # optional: log in directly as alice@root@assetEnv wins over the file for the same key; keys the env does not mention keep the file value.
Bastion
Variable | Default | Note |
| — | required |
|
| |
| — | required |
| — | or |
| — | keeps the secret out of the process env block |
| — | base32 seed or a whole |
| — | as above, by reference |
| — | default system user for every |
| — | key auth instead of a password |
| — | for an encrypted key |
|
| the bastion's menu prompt |
|
| prompt of the paged asset list |
|
| prompt on the target host |
|
|
|
| — | path to a multi-bastion file instead of the keys above |
Behaviour
Variable | Default | Note |
|
| per command |
|
| login + menu navigation |
|
| 0 = keep connections until closed |
|
| surfaces a dead link instead of hanging |
| on |
|
|
| highest number the menu itself owns |
|
| concurrent host connections, LRU eviction |
|
| what the tool returns |
|
| cap on the serialized JSON reply |
|
| what the process holds per shell |
| off | prompt and timing lines on stderr |
Guard and audit
Variable | Default | Note |
| off | disable the read-only allowlist |
| read-only set | comma-separated names or regexes |
|
| comma-separated prefixes |
| unset | JSONL trail of every attempt, refusals included |
| off | include the output text in the trail |
The seed is the secret= value of the authenticator QR: otpauth://totp/JumpServer:alice?secret=JBSWY3DPEHPK3PXP. src/totp.js parses that URI, so pasting the whole URL works too.
jms_ssh_hosts always needs the menu, so when a default account sends
jms_ssh_run straight to the target, the first listing opens a second
connection in the background (one extra login, then reused).
Security
Read-only by default.
jms_ssh_runchecks every pipe segment against an allowlist (cat,tail,journalctl,grep,df,ps,docker logs,kubectl logs…);rm, editors and shells are refused.No second command behind the first.
;,&&,||, backticks,$(and redirection are refused while the allowlist is on —hostname; idused to pass a first-word check and run as root.|is allowed, and each segment is validated on its own.2>&1and2>/dev/nullpass.Prefix rules are not wildcards.
sudo journalctlis allowed, baresudois not.JMS_SSH_ALLOW_ALL=1turns the guard off — only for a bastion account that is itself restricted.Secrets never travel in tool arguments. They come from env vars or the config file; results and errors are redacted.
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.
Audit exists twice. JumpServer records the session; the server can write its own structured trail.
Audit log
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:
export JMS_SSH_AUDIT_LOG=/var/log/jms-mcp/audit.jsonl{"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}
{"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}Written where the tool runs, not by the client, so a client that forgets cannot skip it.
Output text is not recorded, only its size: logs contain secrets more often than anyone expects.
JMS_SSH_AUDIT_OUTPUT=1opts in.clientis the MCP client's ownclientInfo, so several agents can share one file.Append-only, 0600, one write per call. Rotate with logrotate; nothing is re-read.
How this compares
Project | Shape | What we took |
classfang/ssh-mcp-server (~1k★) | 6 tools: execute/upload/download/read-file/write-file/list-servers; | the allowlist hardening: control operators refused, pipes validated per segment |
production-leaning: command+argument whitelist, SFTP, JSONL audit log, imports | audit log is the next thing worth adding | |
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 | |
JumpServer gateways with per-entrance adapters, | confirms that per-entrance adapters are the hard part, not SSH itself | |
JumpServer REST API tools generated from | the direct-login username format above |
The one thing none of them solve is the menu itself — they either assume direct SSH or go through JumpServer's API. Keeping both login paths is what makes this server usable on a locked-down bastion and fast where direct login is allowed.
Install
Not published to npm yet — clone and point the client at src/index.js:
git clone https://github.com/<you>/jms-ssh-mcp.git && cd jms-ssh-mcp && npm install{
"mcpServers": {
"jump": {
"command": "node",
"args": ["/abs/path/jms-ssh-mcp/src/index.js"],
"env": {
"JMS_SSH_HOST": "jumpserver.example.com",
"JMS_SSH_USERNAME": "alice",
"JMS_SSH_PASSWORD_ENV": "JMS_SSH_PASSWORD",
"JMS_SSH_OTP_SECRET_ENV": "JMS_SSH_OTP_SECRET"
}
}
}
}Requires Node 20+.
Layout
src/index.js MCP surface: 4 tools, host-keyed connection registry
src/session.js one bastion session: TOTP login, menu/asset selection, marker-fenced exec
src/window.js bounded output window (head + rolling tail + dropped counter)
src/menu.js asset table and page footer parsing
src/config.js env/config-file resolution, command allowlist
src/totp.js RFC 6238 (no dependency)
test/ TOTP vectors, menu parsing, window bounds, tool-surface contractnpm test runs the unit suite offline (31 tests). A live run needs a reachable bastion:
JMS_SSH_HOST=... JMS_SSH_USERNAME=... JMS_SSH_PASSWORD_ENV=... JMS_SSH_OTP_SECRET_ENV=... node src/index.jsMIT licensed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Manage remote servers, SSH terminals, files, databases and proxies with scoped access and approvals.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Issue, rotate and revoke scoped API-key passes for 25+ providers — the agent never sees a real key
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to securely execute commands on remote hosts via SSH and SFTP, with persistent shells, file transfers, screenshots, and an audit log.5MIT
- AlicenseAqualityBmaintenanceProvides persistent SSH/PTY sessions to a bastion host with asset discovery, permission-gated audited command execution, and batch operations across multiple targets.2317 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables secure execution of arbitrary commands on remote hosts via SSH with OIDC authentication, allowlisted access, and dynamically injected private keys.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to run shell and sudo commands on remote machines through profile-driven SSH sessions, with explicit target guards that prevent commands from hitting the wrong host. It offers bucketed inventory lookup, connectivity diagnostics, keepalive-based connection resilience, and credential-safe configuration management.MIT