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