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

2. Register with Claude Code

3. Verify Installation

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

* 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

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)

2. Username/Password

• Best for: Quick testing, one-off connections, legacy systems

• Security note: Less secure than key-based authentication

3. Direct Private Key Content (Legacy)

• Best for: Programmatic usage, CI/CD systems with key management

• Note: Requires pasting full private key content

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

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

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:

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:

Port conflicts:

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

License

MIT License - see LICENSE file for details.