# remote-ssh-mcp
MCP server for **persistent SSH sessions** with native GUI credential prompts.
[](https://www.npmjs.com/package/remote-ssh-mcp)
## 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
```bash
npm install -g remote-ssh-mcp
```
## Quick Start
Add to your MCP client config:
```json
{
"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:
```json
{
"mcpServers": {
"ssh": {
"command": "remote-ssh-mcp",
"env": {
"SSH_USER": "deploy",
"SSH_PASSWORD": "secret"
}
}
}
}
```
### Host Config File (Optional)
Create `~/.ssh/mcp-hosts.json`:
```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
