hardened-ssh-mcp

A single-purpose MCP server that gives an AI assistant (Claude, or any other MCP-compatible client) the ability to run commands over SSH on one pre-configured host, and only that host - with an explicit per-call confirmation gate before anything actually executes.

This started as a fork of a general-purpose "let the AI run arbitrary PowerShell" MCP tool. That felt like too much uncontrolled surface area for what was actually needed (running specific, known commands on one dev server), so this exists instead: deliberately minimal, deliberately hard to misuse.

Feedback welcome

This was built to solve a real problem, not as a polished product - if you try it, hit an issue, or have a better way to do something here, please open an issue. That's genuinely more useful than a star.

What this is NOT

It is not a general-purpose remote-execution tool. It exposes exactly one tool, run-ssh-command, which can only ever do one thing: send a command over SSH to a fixed user@host set by whoever deploys the server via environment variables. The AI model cannot choose or change the target - it isn't a parameter the model can pass in, it's fixed configuration. It cannot run local commands, and cannot touch the local filesystem directly.

Hardening built in

• Fixed target, not a parameter. Host, user, and identity file come from environment variables set in your MCP client's config, not from anything the model can pass at call time.
• Explicit confirmation gate. The tool requires confirmed: true to actually execute. Calling it without that (the default) just echoes back the command it would run, without running it. The intent is that your AI assistant is instructed to always show you the exact command and wait for your go-ahead before ever setting confirmed: true - this parameter is a technical backstop for that behaviour, not a replacement for it. (With Claude specifically: put this instruction directly in the tool's own description, as this project does, and additionally leave the tool's permission setting on "ask every time" rather than "always allow" in your client.)
• No shell re-interpretation. Arguments are passed as an array via spawn(..., { shell: false }), not built as a concatenated string run through a shell.
• Fails fast, never hangs silently. BatchMode=yes means if key auth doesn't work, the command errors out immediately instead of sitting there waiting for a password prompt nobody can answer. A timeout (default 30s, configurable) kills anything that hangs regardless.
• Local audit log. Every command that actually executes is appended to logs/ssh-command-log.txt with a timestamp and exit code, independent of your AI client's own chat history.

What this does NOT protect against

Being direct about the actual limits, not overselling this:

• confirmed: true is a contract the model is instructed to respect, not something this tool can verify was genuinely approved by a human. The real backstops are your AI client's own instructed behaviour and its per-tool permission prompt.
• Once a command reaches the remote host, it runs as whatever user you configured - this tool doesn't add any privilege restriction on the remote side. If you want defence in depth, give the SSH user its own restricted, least-privilege account with scoped sudo, not your main account.
• This is a small, unaudited piece of code - treat it with the same scepticism as any other tool that can execute commands on your behalf, not as a certified-secure product.

Setup

Prerequisites: Node.js 18+, and a working ssh client on your system.

1. Clone or download this repo.
2. npm install
3. Generate (or reuse) an SSH keypair authorised on the target host, e.g.:

   ssh-keygen -t ed25519 -f ~/.ssh/hardened-ssh-mcp-key
   ssh-copy-id -i ~/.ssh/hardened-ssh-mcp-key.pub youruser@yourhost
   

4. Copy claude_desktop_config.example.json and fill in your own values (host, user, key path), or add the equivalent env block to your existing MCP client config. See that file for the exact shape.
5. Restart your MCP client.
6. In your client's settings, leave this tool's permission on "ask every time," not "always allow."

Configuration reference

Variable	Required	Default	Notes
SSH_USER	yes	-	Remote username
SSH_HOST	yes	-	Remote host (IP or hostname)
SSH_IDENTITY_FILE	yes	-	Absolute path to your private key
SSH_KNOWN_HOSTS_FILE	no	your normal ~/.ssh/known_hosts	See the Windows note below if this path contains spaces
SSH_EXECUTABLE	no	ssh (resolved via PATH)	See the Windows note below
SSH_HOME	no	-	Only needed in the Windows edge case below
SSH_CONNECT_TIMEOUT_SECONDS	no	10
SSH_COMMAND_TIMEOUT_MS	no	30000

Windows note: a real gotcha this project ran into

If you're running this on Windows with an MSIX-packaged AI client (this includes Claude Desktop's Microsoft Store-style installer path), you may hit a genuinely strange failure: Windows' native OpenSSH client (System32\OpenSSH\ssh.exe) exits with code 255 and completely empty output - no stdout, no stderr, not even for ssh -V with no network or keys involved. It works fine run manually, and even works fine from an identical standalone Node.js script - but fails silently the moment it's spawned as a child of the packaged client specifically.

Extensive diagnosis (Process Monitor tracing, elimination of every antivirus/firewall/sandboxing/process-isolation cause) pointed to ssh.exe's own startup code failing during a call into kernel.appcore.dll (a Windows DLL used to query an application's packaging/App Model identity) - plausibly because it inherits an incomplete package identity from an MSIX-packaged ancestor process, and doesn't handle that combination cleanly.

The practical fix: use Git for Windows' bundled SSH client instead of the native one. It's a completely different build (MSYS2/Cygwin-based, not Microsoft's MSVC-built port) and does not exhibit this failure under the identical condition. To use it:

1. Install Git for Windows with the "Use bundled OpenSSH" option (not "Use external OpenSSH").
2. Set SSH_EXECUTABLE to the bundled client's path, typically C:\Program Files\Git\usr\bin\ssh.exe.
3. Set SSH_HOME to your user profile directory (e.g. C:\Users\yourname) - Git's MSYS2-based client needs HOME set explicitly to resolve correctly; Windows' native client does not need this.

If you'd rather keep using Windows' native OpenSSH and are hitting this, an alternative (more involved) workaround is to run this server as a standalone process reached via a stdio-to-HTTP bridge (e.g. mcp-remote) rather than letting your AI client spawn it directly - this avoids the failure entirely by ensuring ssh.exe is never a descendant of the packaged client process, at the cost of needing to start that process yourself before each session. Happy to point you at more detail on this if you land here from a search and it's relevant to your situation - open an issue.

Extending

A per-command allowlist/denylist, or a second, separately configured instance for an additional host, would both be straightforward additions to this pattern.

License

MIT - see LICENSE.