ssh-bridge-mcp

An MCP server that lets any MCP-capable AI client (Claude Code, Claude Desktop, or a client talking to it over HTTP) run commands on a remote machine over SSH — without installing anything on the remote machine. The only requirement on the remote end is a working sshd, same as any normal SSH login.

This exists to bridge the gap between "AI agent wants to help with my remote server" and "that server doesn't have Claude Code / agent tooling installed and I don't want to install it there."

How it works

The server runs locally, wherever your AI client runs (your laptop, typically). It holds one or more live SSH connections in memory and exposes them as MCP tools: ssh_connect, ssh_exec, ssh_read_file, ssh_write_file, ssh_list_sessions, ssh_disconnect. The AI calls these tools; this process is the one that actually opens the socket and authenticates to the remote host — the model itself never touches your credentials.

 Your AI client  <-- MCP (stdio) -->  ssh-bridge-mcp  <-- SSH -->  remote host
 (Claude Code /                       (runs on your
  Claude Desktop)                      local machine)

Related MCP server: ssh-mcp

Install

git clone <this repo>
cd ssh-bridge-mcp
python3 -m venv venv
./venv/bin/pip install -e .

Configure credentials (do this, not inline passwords)

Set these as environment variables on the MCP server process, not as arguments in a chat message — that way the password never enters the model's context or any conversation log.

You can still pass password / key_path directly to the ssh_connect tool call for one-off use, but prefer the environment variable — anything passed as a tool argument is visible to the model and typically ends up in the conversation transcript.

Wire it up

Claude Code — add to .mcp.json in your project (or ~/.claude.json for a global config):

{
  "mcpServers": {
    "ssh-bridge": {
      "command": "/absolute/path/to/ssh-bridge-mcp/venv/bin/python3",
      "args": ["-m", "ssh_bridge_mcp.server"],
      "env": {
        "SSH_BRIDGE_PASSWORD": "your-password-here",
        "SSH_BRIDGE_ALLOWED_HOSTS": "your-server.example.com"
      }
    }
  }
}

Claude Desktop — same shape, in Settings → Developer → Edit Config (claude_desktop_config.json), under mcpServers.

This chat (claude.ai web) — claude.ai runs in the cloud and can't spawn a local process on your machine, so stdio won't reach it. Run the server in streamable-http mode instead and expose it through a tunnel you control (Tailscale Funnel, Cloudflare Tunnel, etc.) — never bind it directly to the open internet. Then add it as a remote MCP connector pointed at your tunnel's URL:

export SSH_BRIDGE_TRANSPORT=streamable-http
export SSH_BRIDGE_HTTP_TOKEN=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
export SSH_BRIDGE_PASSWORD=your-ssh-password
./venv/bin/python3 -m ssh_bridge_mcp.server

This mode requires SSH_BRIDGE_HTTP_TOKEN — the server refuses to start without one — and every request must send Authorization: Bearer <token> or it gets a 401 before any tool runs. Treat that token like a password: whoever holds it can open SSH sessions through this server. Save it somewhere like a password manager, not in the tunnel's public config.

Be deliberate about running this mode at all: it turns "a local script that can SSH into my server" into "a network-reachable service that can SSH into my server." For most use, driving this from Claude Code or Claude Desktop locally over stdio (no network exposure at all) is the simpler and safer path — reach for HTTP mode only when you specifically need claude.ai web or another remote client to reach it.

Usage (once configured)

Just talk to your AI client naturally:

"Connect to 10.0.0.5 as deploy and check disk usage."

It will call ssh_connect, then ssh_exec("df -h"), and report back. Sessions persist across multiple tool calls in a conversation (until you disconnect or the server process restarts), so you don't re-authenticate for every command.

Security notes

• Passwords over SSH are weaker than keys. This works with password auth because that's what was asked for, but consider switching the remote host to key-only auth when you get a chance.

• The default host-key policy auto-trusts new hosts (like a fresh ssh the first time you connect). Set SSH_BRIDGE_STRICT_HOST_KEY=1 once you've connected once and trust known_hosts.

• ssh_exec runs one command per call, not a persistent shell — cd and exported variables from one call don't carry to the next. Chain with && or write a script remotely with ssh_write_file and execute that.

• The deny-pattern list is a seatbelt, not a sandbox. It blocks a handful of obviously catastrophic patterns by string match; it is not a security boundary against a determined or adversarial actor. Don't rely on it to make it safe to point this at a host you don't trust the AI (or whoever else can reach this MCP server) to administer.

• Anyone who can call this server's tools can act as the SSH user it authenticates as. Scope the remote account's permissions accordingly (a limited deploy user beats using root).

Extending

The tool surface here is intentionally minimal. Natural next additions: port forwarding, directory listing/glob over SFTP, binary file transfer, sudo handling, multiplexed persistent shells (via invoke_shell) for interactive/long-running commands, and structured host inventory (an allowlist with per-host default users instead of one global env config).

License

MIT — see LICENSE.