Remote Session Mcp
A Model Context Protocol (MCP) server that enables AI assistants to manage persistent SSH sessions and execute commands on remote servers.
Overview
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/configautomatically 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)
Server Config
{
"mcpServers": {
"remote-session": {
"command": "remote-session-mcp"
}
}
}Project Info
Created At
3 months agoUpdated At
3 months agoAuthor Name
kayoch1nStar
-Language
-License
-Tags
Recommend Servers
View AllFilesystem
@modelcontextprotocol
2 months ago
Serper MCP Server
@garymengcom
A Serper MCP Server
Python
a year ago
Shotapi
@smallhandsome
a day ago