Remote Session Mcp

@kayoch1n

About Remote Session Mcp

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

#ssh #development

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "remote-session": {
      "command": "remote-session-mcp"
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

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.

Frequently asked questions

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.