Remote Session Mcp
About
A Model Context Protocol (MCP) server that enables AI assistants to manage persistent SSH sessions and execute commands on remote servers.
Details
- License
- MIT
Explore
- 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)
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Remote Session McpCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
- 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
Ensure your servers are configured in ~/.ssh/config:
Host production
HostName 192.168.1.100
User deploy
IdentityFile ~/.ssh/id_rsa
// 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"}}
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 |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
| 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 |
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"remote session mcp": {
"remote-session": {
"command": "remote-session-mcp"
}
}
}
}McpServers
{
"remote-session": {
"command": "remote-session-mcp"
}
}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
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
