Remote Session Mcp

What is Remote Session Mcp?

Remote Session Mcp is a Model Context Protocol (MCP) server that enables AI assistants to manage persistent SSH sessions and execute commands on remote servers. It uses invoke_shell() to maintain interactive shell sessions where state (working directory, environment variables) persists across commands, unlike single-command SSH tools.

How to use Remote Session Mcp?

Install the server via uv pip install -e . or pip install -e ., then run remote-session-mcp or python -m remote_session_mcp. Ensure your remote servers are configured in ~/.ssh/config. Integrate with Claude Code by adding a mcpServers entry in your project’s mcp.json. Use the provided tools: hosts, create, execute, close, sessions, upload, and download.

Key features of Remote Session Mcp

• Persistent SSH sessions with state across commands
• Automatic parsing of ~/.ssh/config for connection details
• Supports key-based authentication, custom ports, and jump hosts
• File upload and download capabilities
• List hosts and active sessions
• Configurable session timeout (default 1 hour)

Use cases of Remote Session Mcp

• AI-driven deployment workflows (e.g., navigate, pull, install, restart)
• Debugging and server management with multi-step commands
• Maintaining context across commands without manual state passing
• Automating configuration changes that depend on previous commands
• Securely transferring files to and from remote servers

FAQ from Remote Session Mcp

How does Remote Session Mcp differ from single-command SSH tools?

It maintains persistent interactive shell sessions where state like working directory and environment variables persist across commands, enabling natural multi-step workflows without losing context.

What are the system requirements for using Remote Session Mcp?

The server requires Linux/POSIX and assumes the remote server supports interactive shell sessions. It relies on POSIX‑compatible commands like pwd and echo $?.

How does authentication work?

Authentication uses your ~/.ssh/config settings, supporting key‑based authentication, custom ports, jump hosts, and all standard SSH options. No credentials need to be hardcoded.

Is there a session timeout?

Yes, sessions auto‑close after 1 hour of inactivity. This timeout can be configured in ~/.remote-session/config.json.