# Remote Session MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to manage persistent SSH sessions and execute commands on remote servers.

## Key Advantages

### Persistent Sessions with State

Unlike SSH tools that execute single commands in isolation, this server uses `invoke_shell()` to maintain interactive shell sessions where state persists across multiple commands:

| Capability | Persistent Sessions | Single-Command |
|------------|---------------------|----------------|
| Working directory (`cd`) | Persists | Lost after each command |
| Environment variables (`export`) | Persists | Lost after each command |
| Multi-step workflows | Natural flow | Requires manual context passing |
| AI context awareness | Tracks `pwd` automatically | No state tracking |

**Typical workflow:**
```
create → execute("cd /app") → execute("export ENV=prod") → execute("./deploy.sh") → close
```

This is ideal for AI-driven deployment, debugging, and server management tasks where commands build on each other.

### Automatic SSH Config Integration

- Parses `~/.ssh/config` automatically for connection parameters
- Supports key-based authentication, custom ports, jump hosts, and all standard SSH options
- No need to hardcode credentials or connection details

## Installation

```bash
# Using uv (recommended)
uv pip install -e .

# Or using pip
pip install -e .
```

## Usage

### 1. Configure SSH

Ensure your servers are configured in `~/.ssh/config`:

```
Host production
    HostName 192.168.1.100
    User deploy
    IdentityFile ~/.ssh/id_rsa
```

### 2. Run the MCP Server

```bash
remote-session-mcp
# Or: python -m remote_session_mcp
```

### 3. Claude Code Integration

Create `.claude/settings.json` or `mcp.json` in your project:

```json
{
  "mcpServers": {
    "remote-session": {
      "command": "uv",
      "args": ["run", "remote-session-mcp"],
      "cwd": "/path/to/sshmcp"
    }
  }
}
```

### 4. Available Tools

| Tool | Description |
|------|-------------|
| `hosts` | List all hosts from `~/.ssh/config` |
| `create` | Create a persistent SSH session |
| `execute` | Execute a command (state persists) |
| `close` | Close a session |
| `sessions` | List active sessions |
| `upload` | Upload a file to remote server |
| `download` | Download a file from remote server |

### Example: Deploy an Application

```json
// 1. Create session
{"tool": "create", "arguments": {"host": "production"}}

// 2. Navigate and deploy (state persists)
{"tool": "execute", "arguments": {"session_id": "session_abc", "command": "cd /var/www/myapp"}}
{"tool": "execute", "arguments": {"session_id": "session_abc", "command": "git pull"}}
{"tool": "execute", "arguments": {"session_id": "session_abc", "command": "npm install"}}
{"tool": "execute", "arguments": {"session_id": "session_abc", "command": "sudo systemctl restart myapp"}}

// 3. Close session
{"tool": "close", "arguments": {"session_id": "session_abc"}}
```

## Configuration (Optional)

Create `~/.remote-session/config.json` for custom settings:

```json
{
  "enable_raw_output": false,
  "ssh_config_path": "~/.ssh/config"
}
```

| Option | Default | Description |
|--------|---------|-------------|
| `enable_raw_output` | false | Return raw output with only ANSI codes removed |
| `ssh_config_path` | ~/.ssh/config | Custom path to SSH config file |

## Limitations

- **Linux/POSIX Only** - Assumes POSIX-compatible shells and commands (`pwd`, `echo $?`)
- **Interactive Shell Required** - Remote server must support interactive shell sessions
- **Session Timeout** - Sessions auto-close after 1 hour of inactivity (configurable)