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.

Related MCP server: SSH MCP Server

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.

ssh_clear_known_hosts

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

ssh_exec

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

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.

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.

ssh_upload_file / ssh_download_file

Uploads or downloads files over native SFTP streams.

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.

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