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