SSH MCP Server

# SSH MCP Server A Model Context Protocol (MCP) server that provides SSH session management for Claude Code with browser-based terminal monitoring. ## Features ### Core Functionality - **Persistent SSH Sessions** - Named SSH connections that maintain state across commands - **Interactive Terminal Interface** - Full browser-based terminal with keyboard input and command execution - **Multi-Session Support** - Manage multiple independent SSH sessions simultaneously - **Real-time Output Streaming** - Live terminal output via WebSocket with single clean display - **Command History** - Track executed commands with timestamps and exit codes - **Session Isolation** - Each session maintains separate terminal history and state ### Interactive Terminal Capabilities - **Direct Command Input** - Type commands directly in the browser terminal interface - **Local Echo** - Immediate character display with terminal cursor movement - **Command Line Editing** - Full keyboard navigation (arrows, Home, End, backspace) - **Terminal State Management** - Smart locking/unlocking based on command execution status - **Source Attribution** - Commands from browser users vs Claude Code are properly tracked - **Concurrent Execution** - User and Claude Code commands execute through shared SSH session with queuing ### Advanced Features - **Multiple Authentication Methods** - SSH keys (encrypted/unencrypted), username/password, direct key content - **Command Queuing** - FIFO execution prevents output interleaving between user and Claude Code commands - **WebSocket Communication** - Bidirectional messaging for command execution and output streaming - **Session State Synchronization** - Multiple browser clients stay in sync with terminal state - **Clean Terminal Display** - Single output with preserved ANSI colors and formatting ## Installation & Setup ### Prerequisites - Node.js 16+ and npm - Claude Code CLI installed and configured - SSH server access (for remote connections) - TypeScript (for development) ### 1. Clone and Build ```bash git clone <repository-url> ls-ssh-mcp cd ls-ssh-mcp npm install npm run build ``` ### 2. Register with Claude Code ```bash # Use the installation script (recommended) ./install-mcp.sh # Or manually register claude mcp add ssh node /absolute/path/to/ls-ssh-mcp/dist/src/mcp-server.js ``` ### 3. Verify Installation ```bash # Check that the server was registered claude mcp list ``` **How it works:** - The `install-mcp.sh` script **registers** the server with Claude Code with an auto-discovered port - Claude Code **automatically starts** the server when you use SSH tools - No need to manually start/stop - the server runs on-demand - Web monitoring interface is available at `http://localhost:{port}/session/{session-name}` The installation script handles port discovery, cleanup of existing configurations, and proper registration. ## Usage ### Basic Workflow 1. **Connect to SSH server**: Use `ssh_connect` with your credentials 2. **Execute commands**: Use `ssh_exec` to run commands on the remote server 3. **Monitor sessions**: Use `ssh_get_monitoring_url` to get browser monitoring URL 4. **Manage sessions**: Use `ssh_list_sessions` and `ssh_disconnect` as needed ### Available MCP Tools | Tool | Purpose | Required Parameters | |------|---------|-------------------| | `ssh_connect` | Establish SSH connection | `name`, `host`, `username`, auth method* | | `ssh_exec` | Execute commands on remote server | `sessionName`, `command` | | `ssh_list_sessions` | List all active SSH sessions | None | | `ssh_get_monitoring_url` | Get browser monitoring URL | `sessionName` | | `ssh_disconnect` | Disconnect an SSH session | `sessionName` | \* **Authentication methods**: Choose one: - `password` - SSH user account password - `privateKey` - Direct private key content (+ optional `passphrase` if key is encrypted) - `keyFilePath` - Path to private key file (+ optional `passphrase` if key is encrypted) ### Example Usage ```bash # 1. Connect to a server (multiple authentication methods) # Option A: Username/password authentication ssh_connect name="myserver" host="example.com" username="user" password="pass" # Option B: SSH key file (recommended) ssh_connect name="myserver" host="example.com" username="user" keyFilePath="~/.ssh/id_rsa" # Option C: SSH key file with passphrase (encrypted key) ssh_connect name="myserver" host="example.com" username="user" keyFilePath="~/.ssh/id_ed25519" passphrase="mypassphrase" # Option D: Direct private key content (unencrypted) ssh_connect name="myserver" host="example.com" username="user" privateKey="-----BEGIN OPENSSH PRIVATE KEY-----..." # Option E: Direct private key content (encrypted with passphrase) ssh_connect name="myserver" host="example.com" username="user" privateKey="-----BEGIN OPENSSH PRIVATE KEY-----..." passphrase="keypassword" # 2. Execute commands ssh_exec sessionName="myserver" command="ls -la" ssh_exec sessionName="myserver" command="htop" # 3. Get monitoring URL for real-time terminal ssh_get_monitoring_url sessionName="myserver" # Returns: http://localhost:8082/session/myserver # 4. List all active sessions ssh_list_sessions # 5. Disconnect when done ssh_disconnect sessionName="myserver" ``` ### Interactive Web Terminal The browser interface provides a fully interactive terminal experience: #### Terminal Input & Navigation - **Direct Command Input** - Type commands directly in the terminal, just like a native SSH client - **Local Echo** - Characters appear immediately as you type with cursor movement - **Command Line Editing** - Use arrow keys, Home, End, and backspace for full editing - **Terminal Locking** - Interface locks during command execution, unlocks when complete #### Real-time Features - **Live Output Streaming** - See command results in real-time via WebSocket - **Concurrent Commands** - User-typed commands and Claude Code commands execute seamlessly - **Session Synchronization** - Multiple browser windows stay synchronized - **Command History** - Complete history with timestamps and exit codes #### Advanced Capabilities - **Source Attribution** - Terminal tracks whether commands came from user input or Claude Code - **Queue Management** - Commands execute in order without output mixing - **State Persistence** - Session state maintained across browser reconnects - **Clean Output Display** - Single command output without duplication or formatting issues **Usage**: Navigate to the monitoring URL and interact with the terminal exactly like a local SSH session. Type commands, press Enter, and see results instantly. Claude Code can also execute commands in the same session without interference. ## SSH Authentication Methods The server supports multiple SSH authentication methods with automatic fallback: ### 1. SSH Key Files (Recommended) - **Best for**: Regular usage, automated deployments, security-conscious users - **Supports**: RSA, ED25519, ECDSA key formats - **Encryption**: Both encrypted (with passphrase) and unencrypted keys - **Path expansion**: Supports tilde expansion (`~/.ssh/id_rsa`) ```bash # Unencrypted key ssh_connect name="prod" host="server.com" username="deploy" keyFilePath="~/.ssh/id_ed25519" # Encrypted key with passphrase ssh_connect name="secure" host="server.com" username="admin" keyFilePath="~/.ssh/id_rsa" passphrase="mysecretpass" ``` ### 2. Username/Password - **Best for**: Quick testing, one-off connections, legacy systems - **Security note**: Less secure than key-based authentication ```bash ssh_connect name="test" host="server.com" username="user" password="password" ``` ### 3. Direct Private Key Content (Legacy) - **Best for**: Programmatic usage, CI/CD systems with key management - **Note**: Requires pasting full private key content ```bash ssh_connect name="ci" host="server.com" username="deploy" privateKey="-----BEGIN OPENSSH PRIVATE KEY-----..." ``` ### Authentication Priority 1. `privateKey` (if provided) - highest priority 2. `keyFilePath` (if provided) - recommended method 3. `password` (if provided) - fallback method ## Configuration ### Environment Variables - `SSH_TIMEOUT` - SSH operation timeout in milliseconds (default: 30000) - `MAX_SESSIONS` - Maximum concurrent SSH sessions (default: 10) - `LOG_LEVEL` - Logging level: 'error', 'warn', 'info', 'debug' (default: 'info') Web server port is automatically discovered and managed by the installation script. ## Development ### Setup Development Environment ```bash # Install dependencies npm install # Run in development mode with auto-reload npm run dev # Run tests npm test # Run E2E tests (requires SSH server on localhost) npm run test:e2e # Build for production npm run build # Lint code npm run lint ``` ### Testing Requirements For running tests, you need: - SSH server running on localhost - Test user account: `test_user` with password `password123` - Or configure your own test credentials in the test files ### Project Structure ``` ├── src/ │ ├── mcp-server.ts # Main server orchestrator │ ├── mcp-ssh-server.ts # MCP protocol handler │ ├── web-server-manager.ts # Web interface server + WebSocket handlers │ ├── ssh-connection-manager.ts # SSH session management + command queuing │ └── types.ts # TypeScript definitions + command source types ├── static/ # Interactive xterm.js terminal interface │ ├── terminal-input-handler.js # Browser input handling and state management │ └── [xterm.js assets] # Terminal rendering components ├── plans/ │ ├── interactive-terminal-epic.md # Complete implementation documentation │ └── [other planning docs] # Additional project planning ├── tests/ # Comprehensive test suite │ ├── story*.test.ts # User story validation tests │ ├── e2e-*.test.ts # End-to-end functionality tests │ └── manual-tests/ # Manual testing scripts and plans ├── install-mcp.sh # Installation script └── dist/ # Compiled output ``` ## Security Considerations - SSH sessions are kept in memory only - Credentials are not persisted - Web interface runs on localhost by default - Use SSH key authentication when possible ## Architecture ### Overall Design The SSH MCP Server implements a sophisticated architecture that seamlessly integrates Claude Code's MCP tools with interactive browser terminals: ``` ┌─────────────────┐ stdio ┌─────────────────┐ WebSocket ┌─────────────────┐ │ Claude Code │◄──────────►│ MCP Server │◄──────────────►│ Browser Terminal│ └─────────────────┘ commands └─────────────────┘ bidirectional └─────────────────┘ │ ▼ ┌─────────────────┐ │ SSH Connection │ │ Manager │ │ (with Queue) │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ Remote SSH │ │ Server │ └─────────────────┘ ``` ### Core Components - **MCP Server**: Handles Claude Code communication via stdio protocol (no network port) - **Web Server**: Provides interactive terminal interface via HTTP and WebSocket - **SSH Connection Manager**: Centralized session management with command queuing - **Interactive Terminal**: Browser-based xterm.js interface with input handling ### Key Architectural Features #### 1. **Unified Command Execution** - Both Claude Code tools and browser user input execute through the same SSH sessions - Commands are queued in FIFO order to prevent output interleaving - Source attribution tracks whether commands came from "user" or "claude" #### 2. **Real-time Communication** - **MCP Protocol**: stdio transport between Claude Code and server - **WebSocket**: Bidirectional communication between browser and server - **SSH Connection**: Persistent shell channels with streaming output #### 3. **State Management** - **Session Persistence**: SSH sessions maintain state across all command sources - **Terminal Synchronization**: Multiple browser clients stay synchronized - **Queue Management**: Commands execute sequentially with proper cleanup ### Port Management - **MCP Communication**: Uses stdio transport only (stdin/stdout with Claude Code) - **Web Interface**: Single auto-discovered port serves both HTTP routes and WebSocket connections - **Port Discovery**: Installation script discovers available port and stores as `WEB_PORT` environment variable - **URL Generation**: MCP tools return monitoring URLs pointing to the web interface ### Interactive Terminal Architecture #### Browser-Side Components - **xterm.js Terminal**: Renders terminal interface with full VT100 compatibility - **Input Handler**: Manages keyboard input, local echo, and command submission - **WebSocket Client**: Handles bidirectional communication with server - **State Manager**: Tracks terminal lock/unlock state and command execution #### Server-Side Processing - **WebSocket Handler**: Processes terminal input messages from browser - **Command Router**: Routes commands to SSH connection manager with source attribution - **Output Broadcaster**: Streams command results back to all connected clients - **Queue Coordinator**: Ensures proper execution order for mixed command sources ### Deployment Modes - **Production**: Claude Code automatically starts server on-demand when SSH tools are used - **Development**: Manual testing with independent port discovery - **Interactive Mode**: Browser clients can connect and interact with existing SSH sessions ### Data Flow 1. **Claude Code Command**: `ssh_exec` → MCP Server → SSH Manager → Queue → SSH Session 2. **Browser Command**: Terminal Input → WebSocket → Web Server → SSH Manager → Queue → SSH Session 3. **Output Streaming**: SSH Session → SSH Manager → WebSocket → Browser Terminal 4. **State Updates**: Command completion → Terminal unlock (for user commands only) ## Troubleshooting ### Common Issues **Server not starting after registration:** ```bash # Check if Claude Code recognizes the server claude mcp list # Verify build exists ls -la dist/src/mcp-server.js # Test the server directly node dist/src/mcp-server.js ``` **Port conflicts:** ```bash # Re-run installation to discover new port ./install-mcp.sh # Verify new configuration claude mcp get ssh ``` **SSH connection failures:** - Verify SSH server is running and accessible - Check credentials (username/password or privateKey) - Ensure SSH server allows password authentication if using passwords **Web interface not accessible:** - Use `ssh_get_monitoring_url` to get the correct URL with current port - Check that the server is running: `ps aux | grep mcp-server` ### Logs and Debugging ```bash # Enable debug logging when using Claude Code export LOG_LEVEL=debug # Check MCP server configuration claude mcp get ssh # Test server manually with debug output LOG_LEVEL=debug node dist/src/mcp-server.js ``` ## License MIT License - see [LICENSE](LICENSE) file for details.