Remote Session Mcp

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

# 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

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

// 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"
}

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)