AI: Let me SSH into your server and check the logs.
AI: [runs: ssh user@server "cat /var/log/app.log"]  # Opens connection, runs, closes
AI: Now let me check disk space.
AI: [runs: ssh user@server "df -h"]  # Opens ANOTHER connection, runs, closes

AI: [starts session → ssh user@server]
AI: [runs: cd /var/log]           # Working directory persists
AI: [runs: tail -f app.log]       # Can run interactive commands
AI: [sends: Ctrl+C]               # Can send signals
AI: [downloads: error.log]        # Can transfer files
AI: [forwards: 5432 → postgres]   # Can forward ports
AI: [shares session]              # Collaborate in real-time
AI: [ends session]                # Explicit close when done

# Clone the repository
git clone https://github.com/raghavharness/remote-shell-mcp
cd mcp-remote-shell

# Install dependencies
npm install

# Build
npm run build

{
  "mcpServers": {
    "remote-shell": {
      "command": "node",
      "args": ["/path/to/mcp-remote-shell/dist/index.js"]
    }
  }
}

# Start a session (auto-detected):
shell(command="ssh user@hostname")
shell(command="gcloud compute ssh my-vm --zone us-central1-a")

# Run commands in session:
shell(command="ls -la")
shell(command="cd /var/log")

# Smart wait auto-adjusts for slow commands:
shell(command="npm install")  # Waits 20s automatically

# Interrupt (Ctrl+C):
shell(command="//stop")

# End session:
shell(command="//end")

# List recent blocks
remote_blocks_list(limit=10)

# Get a specific block
remote_block_get(blockId="block-5")

# Search through blocks
remote_blocks_search(query="error")

# Copy just the output (no command)
remote_block_copy(blockId="block-5")

# Tag blocks for organization
remote_block_tag(blockId="block-5", tags=["important", "debug"])

# Find error blocks
remote_blocks_errors()

# Split the current pane
remote_pane_split(direction="horizontal")
remote_pane_split(direction="vertical")

# List panes
remote_pane_list()

# Switch to a pane
remote_pane_focus(paneId="pane-1")

# Run command in specific pane (without switching)
remote_pane_exec(paneId="pane-1", command="tail -f /var/log/app.log")

# Broadcast command to ALL panes
remote_pane_broadcast(command="uptime")

# Close a pane
remote_pane_close(paneId="pane-1")

# Check if session is waiting for input
remote_session_check_prompt()

# Send text input
remote_session_input(input="my-response")

# Send password (hidden in output)
remote_session_password(password="secret123")

# Send Y/N confirmation
remote_session_confirm(confirm=true)

# Create a swarm of SSH connections
remote_swarm_create(
  name="web-servers",
  method="ssh",
  targets=[
    { "id": "web1", "host": "10.0.0.1", "username": "admin" },
    { "id": "web2", "host": "10.0.0.2", "username": "admin" },
    { "id": "web3", "host": "10.0.0.3", "username": "admin" }
  ]
)

# Create a GCloud swarm
remote_swarm_create(
  name="gcp-cluster",
  method="gcloud",
  targets=[
    { "id": "node1", "instance": "gke-node-1", "zone": "us-central1-a" },
    { "id": "node2", "instance": "gke-node-2", "zone": "us-central1-a" }
  ]
)

# Broadcast command to all targets
remote_swarm_exec(swarmId="swarm-1", command="uptime")
remote_swarm_exec(swarmId="swarm-1", command="df -h")

# Send input to all sessions (e.g., for sudo password)
remote_swarm_input(swarmId="swarm-1", input="mypassword")

# Interrupt all sessions
remote_swarm_interrupt(swarmId="swarm-1")

# List swarms
remote_swarm_list()

# Get detailed swarm status
remote_swarm_status(swarmId="swarm-1")

# End a swarm
remote_swarm_end(swarmId="swarm-1")
remote_swarm_end(swarmId="all")  # End all swarms

# Enable streaming with auto-interrupt on errors
remote_stream_enable(autoInterrupt=true)

# Add custom error patterns
remote_stream_enable(
  autoInterrupt=true,
  errorPatterns=["CRITICAL", "OutOfMemory", "Segfault"]
)

# Check streaming status
remote_stream_status()

# Disable streaming
remote_stream_disable()

# Share the current session
remote_session_share(permissions="view")
# Returns: http://localhost:3847/share/abc123

# Share with control access and password
remote_session_share(permissions="control", password="secret123")

# List active shares
remote_shares_list()

# Update share settings
remote_share_update(shareId="abc123", permissions="control")

# Stop sharing
remote_session_unshare()

# Upload a local file to remote:
remote_file_upload(localPath="./config.yml", remotePath="/etc/myapp/config.yml")

# Download a remote file:
remote_file_download(remotePath="/var/log/app.log", localPath="./app.log")

# List remote directory:
remote_file_list(path="/var/log")

# Local forward: access remote PostgreSQL on localhost:5433
remote_port_forward_local(localPort=5433, remoteHost="localhost", remotePort=5432)

# Remote forward: expose local dev server to remote
remote_port_forward_remote(remotePort=8080, localPort=3000)

# List active forwards:
remote_port_list()

# Stop a forward:
remote_port_stop(forwardId="fwd-1")

User: Connect to prod and figure out why the app is slow

Claude: [shell: gcloud compute ssh prod-server --project myapp]
        Session started: gcloud:prod-server
        Working directory: /home/user

Claude: [shell: top -bn1 | head -20]
        CPU at 95%! Checking what's using it...
        [block-1]

Claude: [shell: ps aux --sort=-%cpu | head -10]
        App process using 92% CPU.
        [block-2]

Claude: [remote_blocks_search: query="error"]
        Found 3 matches in block history...

Claude: [remote_pane_split: direction="horizontal"]
        Split into 2 panes for monitoring

Claude: [remote_pane_exec: paneId="pane-1", command="tail -f /var/log/app.log"]
        Watching logs in pane-1...

Claude: [remote_session_share: permissions="view"]
        Shared session: http://localhost:3847/share/xyz789
        (Ops team can watch live)

Claude: [shell: sudo systemctl restart myapp]
        Service restarted.

Claude: [shell: //end]
        Session ended. App should be recovering.

┌─────────────────┐     ┌───────────────────────────────┐     ┌─────────────────┐
│   AI Client     │────▶│      Remote Shell MCP         │────▶│  Remote Server  │
│ (Claude Code)   │ MCP │          Server               │     │  (SSH/gcloud)   │
└─────────────────┘     └───────────────────────────────┘     └─────────────────┘
                                    │
                        ┌───────────┴───────────┐
                        ▼                       ▼
                ┌───────────────┐       ┌───────────────┐
                │Session Manager│       │   Features    │
                │ - Sessions    │       │ - Blocks      │
                │ - Panes       │       │ - Persistence │
                │ - History     │       │ - Sharing     │
                └───────────────┘       │ - FileTransfer│
                                        │ - PortForward │
                                        │ - SmartWait   │
                                        └───────────────┘
                                                │
                                        ┌───────┴───────┐
                                        ▼               ▼
                                ┌───────────┐   ┌───────────┐
                                │ WebSocket │   │ Web Client│
                                │  Server   │──▶│ (Browser) │
                                └───────────┘   └───────────┘

src/
├── index.ts              # MCP server entry point
├── session-manager.ts    # Session lifecycle management
├── types.ts              # TypeScript interfaces
├── features/
│   ├── blocks.ts         # Block-based output (v4.0)
│   ├── panes.ts          # Pane management (v4.0)
│   ├── persistence.ts    # Session persistence (v4.0)
│   ├── heartbeat.ts      # Connection monitoring (v4.0)
│   ├── sharing/          # Session sharing (v4.0)
│   │   ├── share-manager.ts
│   │   └── ws-server.ts
│   ├── file-transfer.ts  # SFTP/SCP operations
│   ├── port-forward.ts   # Port forwarding
│   ├── smart-wait.ts     # Command timeout logic
│   ├── directory-tracker.ts
│   ├── reconnect.ts
│   ├── output-search.ts
│   └── streaming.ts
├── tools/
│   ├── shell.ts          # Main shell tool
│   ├── session-tools.ts  # Session management
│   ├── file-tools.ts     # File transfer tools
│   ├── port-tools.ts     # Port forward tools
│   ├── block-tools.ts    # Block tools (v4.0)
│   ├── pane-tools.ts     # Pane tools (v4.0)
│   └── share-tools.ts    # Share tools (v4.0)
├── prompts/
│   └── index.ts          # MCP prompts
└── utils/
    ├── ansi.ts           # Terminal formatting
    ├── terminal-ui.ts    # UI helpers
    └── patterns.ts       # Command detection

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run integration tests (local only)
npm test

# Run with live SSH (requires TEST_SSH_HOST, TEST_SSH_USER)
TEST_SSH_HOST=myserver TEST_SSH_USER=myuser npm test