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:

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

# 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

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

3. Claude Code Integration

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

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

4. Available Tools

Example: Deploy an Application

// 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:

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

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)