# remote-ssh-mcp

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

[![npm version](https://badge.fury.io/js/remote-ssh-mcp.svg)](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