mcp-ssh

A production-grade Model Context Protocol (MCP) server for cross-platform SSH remote execution, automated passwordless key management, Windows Session 0 interactive desktop process launching, and SFTP file transfers.

---

How It Works

Agent (Claude / Antigravity / Custom Script)
      │  stdio JSON-RPC (MCP Protocol)
      ▼
mcp-ssh Server (Node.js + TypeScript)
      │  Native SSH2 / SFTP Streams
      ▼
Remote Target Machine
   ├─ Windows (Win32-OpenSSH, Base64 UTF-16LE, Session 0 Bypass, Administrators ACLs)
   ├─ Linux   (OpenSSH, bash, ~/.ssh/authorized_keys)
   └─ macOS   (systemsetup remotelogin, zsh/bash)

The agent connects over standard stdio JSON-RPC. mcp-ssh encapsulates all platform matrix quirks, UTF-16LE PowerShell encoding, Session 0 Task Scheduler handoffs, 8,191-character command line walls, and key ACL permissions ngầm in code so the agent receives clean, predictable, structured JSON results.

---

Core Capabilities

• Zero Local Client Shell Dependencies: Written in pure TypeScript with ssh2. Does not require WSL, Git Bash, sshpass, iconv, or local ssh binaries on Windows or macOS clients.
• Automated PowerShell Command Encoding: Converts Windows command bodies to Base64 UTF-16LE strings (powershell.exe -EncodedCommand), removing all nested quote escaping errors.
• Session 0 Desktop Handoff (desktop: true): Solves the classic Win32-OpenSSH issue where GUI apps launch invisibly in Session 0. Resolves owner of active explorer.exe and schedules a temporary Task Scheduler job with LogonType Interactive to launch GUI apps on the user's active desktop (Session 1).
• 8,191-Character Boundary Auto-Fallback: Automatically detects when encoded PowerShell payloads exceed the 8,000-character cmd.exe length limit wall, seamlessly uploading a UTF-8 BOM temporary script via SFTP and executing it with powershell -File.
• First-Connect & Key Lifecycle:
  • Connection probe with target OS auto-detection.
  • Generates OpenSSH RDP Bootstrap 1-liners when target SSH is uninstalled or port 22 is closed.
  • Clears stale entries from ~/.ssh/known_hosts when hosts are re-imaged (REMOTE HOST IDENTIFICATION HAS CHANGED).
  • Deploys ed25519 key pairs with OS-strict ACLs (icacls SYSTEM:F Administrators:F on Windows; chmod 600 on Unix).
  • Revokes key access or clears authorized keys via ssh_remove_passwordless.

---

Quick Start

1. Build the MCP Server

cd claude/mcp-ssh
npm install
npm run build

2. Register with Claude Desktop / Claude Code

Claude Code CLI:

# Windows:
claude mcp add ssh -- node "C:/path/to/my_notes/claude/mcp-ssh/dist/index.js"

# macOS / Linux:
claude mcp add ssh -- node "/absolute/path/to/my_notes/claude/mcp-ssh/dist/index.js"

Claude Desktop Configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": [
        "/absolute/path/to/my_notes/claude/mcp-ssh/dist/index.js"
      ]
    }
  }
}

---

Tool Reference

ssh_test_connection

Probes SSH connectivity, authenticates, and auto-detects target OS (windows, linux, mac). If target port 22 is closed, outputs an OpenSSH RDP bootstrap script.

Parameter	Type	Required	Description
host	string	Yes	Target hostname or IP address
username	string	Yes	SSH username
password	string	No	SSH password
privateKeyPath	string	No	Path to private key file
port	number	No	SSH port (default: 22)

---

ssh_clear_known_hosts

Removes stale host key entries matching host from ~/.ssh/known_hosts to resolve host key collision errors.

Parameter	Type	Required	Description
host	string	Yes	Hostname or IP to clear

---

ssh_exec

Executes remote commands over SSH across Windows, Linux, and macOS.

Parameter	Type	Required	Description
host	string	Yes	Target host IP or domain
username	string	Yes	SSH username
command	string	Yes	Command line or script body
password	string	No	SSH password
privateKeyPath	string	No	Path to private key file
targetOs	enum	No	auto (default), windows, linux, mac
desktop	boolean	No	Windows only: launch in Session 1 interactive GUI desktop (false default)
session	number	No	Windows only: force specific session ID
port	number	No	SSH port (default: 22)

Response Format:

EXIT CODE: 0

--- STDOUT ---
WindowsProductName    OsVersion  OsArchitecture
------------------    ---------  --------------
Windows 10 Enterprise 10.0.26200 64-bit

--- STDERR ---
(empty)

---

ssh_setup_passwordless

Generates an ed25519 key pair locally if missing, deploys public key to target host with strict ACLs, and verifies key login.

Parameter	Type	Required	Description
host	string	Yes	Target host IP
username	string	Yes	Target username
password	string	Yes	Password required for initial key copy
keyPath	string	No	Private key path (defaults to ~/.ssh/id_ed25519)
targetOs	enum	No	auto (default), windows, linux, mac
port	number	No	SSH port (default: 22)

---

ssh_remove_passwordless

Removes a specific public key entry or clears all public key entries from the target authorized keys file, revoking key-based login.

Parameter	Type	Required	Description
host	string	Yes	Target host IP
username	string	Yes	Target username
password	string	No	SSH password
privateKeyPath	string	No	Private key path
keyPathToRemove	string	No	Local public key path to remove
removeAllKeys	boolean	No	Clear ALL authorized keys on target (false default)
port	number	No	SSH port (default: 22)

---

ssh_upload_file / ssh_download_file

Uploads or downloads files over native SFTP streams.

Parameter	Type	Required	Description
host	string	Yes	Target host IP
username	string	Yes	SSH username
localPath	string	Yes	Local file path
remotePath	string	Yes	Remote target path
password	string	No	SSH password
privateKeyPath	string	No	Private key path

---

ssh_generate_rdp_bootstrap

Generates a self-contained 1-liner PowerShell script to paste into an RDP session to install Win32-OpenSSH, open firewall port 22, and set autostart services.

Parameter	Type	Required	Description
host	string	No	Target host IP or hostname
userType	enum	No	admin (elevated) or user (triggers UAC prompt)

---

Status & Verification

• TypeScript Compilation: Clean build (npm run build, 0 errors).
• Live Verification against Windows Host: Tested against live Windows 10 Enterprise target:
  • ssh_test_connection: Passed (connected, target OS auto-detected as WINDOWS).
  • ssh_exec: Passed (Base64 UTF-16LE executed Get-ComputerInfo, exit code 0).
  • ssh_exec (desktop: true): Passed (Session 1 task scheduled for active explorer.exe owner, executed and cleaned up without trace).

---

Security Model

• Trusted Local Engine: Designed for single-user internal developer and QA automation workflows.
• Credential Protection: Passwords and private keys remain in memory within the stdio MCP process during execution and are never logged to stdout or stored in command line histories.
• Strict Key Permissions: Automatically enforces OpenSSH ACL requirements on target machines (SYSTEM:F + Administrators:F for Windows administrators_authorized_keys; chmod 600 for Unix authorized_keys).

---

License

MIT