hardened-ssh-mcp

hardened-ssh-mcp

A single-purpose MCP server that gives an AI assistant (Claude, or any otherMCP-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 muchuncontrolled surface area for what was actually needed (running specific, known commands on one dev server), sothis 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 abetter 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 canonly ever do one thing: send a command over SSH to a fixed user@host set by whoever deploys the server viaenvironment variables. The AI model cannot choose or change the target - it isn't a parameter the model can passin, 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 MCPclient'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 AIassistant is instructed to always show you the exact command and wait for your go-ahead before ever settingconfirmed: true - this parameter is a technical backstop for that behaviour, not a replacement for it. (WithClaude specifically: put this instruction directly in the tool's own description, as this project does, andadditionally 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 asa concatenated string run through a shell.
• Fails fast, never hangs silently. BatchMode=yes means if key auth doesn't work, the command errors outimmediately 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 atimestamp 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 wasgenuinely approved by a human. The real backstops are your AI client's own instructed behaviour and its per-toolpermission prompt.
• Once a command reaches the remote host, it runs as whatever user you configured - this tool doesn't add anyprivilege 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 executecommands 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 theequivalent 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

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 MicrosoftStore-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 evenfor ssh -V with no network or keys involved. It works fine run manually, and even works fine from an identicalstandalone Node.js script - but fails silently the moment it's spawned as a child of the packaged clientspecifically.

Extensive diagnosis (Process Monitor tracing, elimination of every antivirus/firewall/sandboxing/process-isolationcause) pointed to ssh.exe's own startup code failing during a call into kernel.appcore.dll (a Windows DLL usedto query an application's packaging/App Model identity) - plausibly because it inherits an incomplete packageidentity 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 completelydifferent build (MSYS2/Cygwin-based, not Microsoft's MSVC-built port) and does not exhibit this failure under theidentical 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 HOMEset 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) workaroundis 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 thecost of needing to start that process yourself before each session. Happy to point you at more detail on this ifyou 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 bothbe straightforward additions to this pattern.

License

MIT - see LICENSE.