remote-ssh-mcp

MCP server for persistent SSH sessions with native GUI credential prompts.

Features

• 🔗 Persistent Sessions - Connections survive across multiple commands
• 🔐 GUI Credential Prompts - Native dialogs on Linux/macOS/Windows
• 📁 File Transfer - Upload/download via SFTP
• ⏱️ Background Commands - Run long tasks without blocking
• 🔄 Session Reuse - Automatic connection pooling per host
• 🛡️ Secure - Per-process secrets, localhost-only helper

Installation

npm install -g remote-ssh-mcp

Quick Start

Add to your MCP client config:

{
  "mcpServers": {
    "ssh": {
      "command": "remote-ssh-mcp"
    }
  }
}

That's it! Connect to servers and credentials will be prompted via native GUI.

Configuration

Environment Variables (Optional)

Skip GUI prompts by setting credentials:

{
  "mcpServers": {
    "ssh": {
      "command": "remote-ssh-mcp",
      "env": {
        "SSH_USER": "deploy",
        "SSH_PASSWORD": "secret"
      }
    }
  }
}

Host Config File (Optional)

Create ~/.ssh/mcp-hosts.json:

{
  "defaults": { "username": "admin" },
  "hosts": {
    "prod.example.com": {
      "username": "deploy",
      "keyPath": "~/.ssh/deploy_key"
    }
  }
}

Tools

Tool	Description
ssh_connect	Connect to SSH server, returns session_id
ssh_exec	Execute command (with optional background mode)
ssh_read_buffer	Read terminal output history
ssh_disconnect	Close a session
list_sessions	List active sessions
scp_upload	Upload file via SFTP
scp_download	Download file via SFTP

Example Usage

1. ssh_connect(host="server.com", auth_mode="password")
   → { session_id: "abc-123", status: "connected" }

2. ssh_exec(session_id="abc-123", command="cd /app && git pull")
   → { stdout: "Already up to date.", exit_code: 0 }

3. ssh_exec(session_id="abc-123", command="npm run build", background=true)
   → { status: "running", pid: "12345" }

4. ssh_read_buffer(session_id="abc-123", lines=50)
   → { lines: ["Building...", "Done!"], total_buffered: 150 }

GUI Requirements

For credential prompts:

• Linux: zenity (apt install zenity)
• macOS: Built-in (osascript)
• Windows: Built-in (PowerShell)

Without GUI, use environment variables or config file.

Security

• Credentials prompted via native OS dialogs
• Never logged or written to disk
• Per-process authentication tokens
• Localhost-only credential helper
• Sessions auto-expire after 15 min inactivity

License

MIT