ssh‑mcp‑server

What it is

ssh‑mcp‑server is a Node‑JS utility that acts as a bridge between an AI‑assistant (or any client that speaks the Model Context Protocol, MCP) and a remote SSH server. It runs locally, keeps the SSH credentials on the host, and exposes a set of MCP‑compatible tools (execute‑command, upload, download, read‑file, write‑file, job‑control, etc.) so that the AI can ask the server to run commands or move files without ever seeing the private keys or passwords.

Why it matters for AI/ML workflows

• Secure remote execution – LLM‑driven agents often need to perform real‑world actions (e.g., provisioning a VM, pulling logs, deploying code). By routing those actions through MCP, the model never gets raw SSH credentials, reducing the attack surface.
• Standardised interface – MCP is a protocol used by several AI‑coding assistants (Claude Code, Cursor, etc.). This server implements the spec, letting any MCP‑aware assistant treat a remote host as a first‑class tool.
• Fine‑grained safety controls – Built‑in command whitelist/blacklist, output size limits, and path restrictions let operators lock the AI down to safe operations (read‑only diagnostics, log collection, etc.).
• Supports complex environments – Works with password, key‑based, and 2FA authentication; can hop through bastion hosts, SOCKS/HTTP proxies, and even run commands inside containers via a template.

Core features (as described in the README)

Feature	What it does
Multiple authentication methods	Password, private‑key (with optional passphrase), SSH‑agent, and keyboard‑interactive 2FA.
Command whitelist / blacklist	Regex‑based allow‑/deny‑lists; white‑list takes precedence, preventing dangerous pipelines or redirections.
Transport modes	exec (default, supports SFTP) and shell (persistent shell, useful for bastion hosts, but no file transfer).
File transfer	upload / download via SFTP, with recursive directory support and configurable allowed path lists.
Job management	job‑start, job‑status, job‑kill, job‑list for long‑running background tasks that survive server restarts.
Command templating	Wrap each command in a user‑supplied template (e.g., sudo bash -c <quotedCommand> or docker exec …).
Multi‑host configuration	Single JSON config file, --ssh JSON strings, legacy comma‑separated syntax, or comma‑separated --host values that pull from ~/.ssh/config.
Proxy support	SOCKS5, HTTP, HTTPS proxies via --proxy (or legacy --socksProxy).
Output & resource limits	Max stdout/stderr size (default 10 MiB), per‑command timeout, keep‑alive settings, and optional PTY allocation.
Zero‑install execution	Run with npx @fangjunjie/ssh-mcp-server … – no global install required.

Who might use it

• AI‑coding assistants that need to run real commands on a user’s infrastructure (e.g., Claude Code, Cursor, GitHub Copilot Chat).
• DevOps teams building LLM‑driven bots for automated diagnostics, log collection, or deployment.
• Security‑focused users who want to expose only a narrow set of SSH actions to an AI model.
• Researchers experimenting with autonomous agents that interact with cloud or on‑prem servers.

Getting started (quick steps from the README)

1. Install / run – npx -y @fangjunjie/ssh-mcp-server … (the -y flag skips the npm install prompt).
2. Create an MCP config – copy one of the example JSON snippets (e.g., simple password auth) into your MCP client’s mcp.json.
3. Optionally add a whitelist – restrict commands to safe ones like ls, cat, df.
4. Invoke a tool – from the AI assistant send a request such as:

   { "tool": "execute-command", "params": { "cmdString": "ls -al", "connectionName": "dev" } }
   

5. Watch the response – the server returns the command output, exit code, and any error metadata.

Limitations / open points (as per the README)

• No built‑in rate‑limiting – you need an external firewall or reverse proxy to protect against DoS.
• shell mode disables file transfer because SFTP is not available over a persistent shell.
• Output size limits are hard‑coded per connection; setting maxOutputBytes to 0 disables the guard but is discouraged.
• The server assumes a POSIX sh environment on the remote host for background jobs.

---

All information above is taken directly from the project's README; no additional features have been inferred.