Teleport to any shell.
Your servers, one keystroke away.
---
CLI tool for managing SSH connections with an interactive TUI, session monitoring, and MCP integration for Claude Desktop.
## Prerequisites
- **Go 1.25+**
- **jq** — JSON processor (`brew install jq`)
- **Bash / Zsh**
## Install
```bash
make build # compile binaries
make install # install to ~/.local/share/shellport + symlink to ~/.local/bin
```
Add to `~/.zshrc` if needed:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
## Usage
```
shellport Interactive host selector (TUI)
shellport add Add a new SSH host
shellport ls List all saved hosts
shellport show Show host details
shellport edit Edit a host
shellport rm Remove a host
shellport mcp Start MCP server (for Claude Desktop)
shellport --version Show version
shellport --help Show help
```
### Adding a host
```bash
$ shellport add
Name My Server
ID / slug [my-server]
Host / IP 10.0.1.50
SSH user [ec2-user] deploy
Port [22]
Identity file ~/.ssh/prod_key
Tags (comma) prod, web
Note Main web server
✓ Host 'My Server' saved.
```
### Interactive selector
Run `shellport` with no arguments to open the TUI:
```
shellport 3
──────────────────────────────────
/
──────────────────────────────────
▶ Production Web deploy@10.0.1.1 [prod, web]
Staging DB admin@10.0.2.1 [staging]
Dev Box dev@192.168.1.100
──────────────────────────────────
↑↓ nav | enter connect | a add | e edit | d delete | q quit
```
**Keybindings:**
| Key | Action |
|-----|--------|
| `↑` / `k` | Move up |
| `↓` / `j` | Move down |
| `g` / `Home` | Go to top |
| `G` / `End` | Go to bottom |
| `Enter` | Connect via SSH |
| `a` | Add host |
| `e` | Edit selected host |
| `d` | Delete selected host |
| `/` (type) | Filter hosts |
| `Esc` | Clear filter / quit |
| `q` | Quit |
### SSH session monitoring
When connecting through the TUI, `ssh-watch` wraps the SSH session and records:
- Terminal output (last 300 lines)
- Command history (last 100 commands)
- Current directory
- Connection metadata
Session data is written to `~/.shellport/session.json` every 500ms.
## MCP Integration (Claude Desktop)
The MCP server exposes your SSH hosts and active session to Claude Desktop.
### Setup
Add to your Claude Desktop MCP config (or use the `.mcp.json` in this repo):
```json
{
"mcpServers": {
"shellport": {
"command": "/path/to/bin/shellport-mcp-server",
"args": []
}
}
}
```
Or start manually:
```bash
shellport mcp
```
### Available MCP tools
| Tool | Description |
|------|-------------|
| `terminal_get_session` | Active session info (host, user, uptime, etc.) |
| `terminal_get_output` | Last N lines of terminal output |
| `terminal_get_history` | Command history with timestamps |
| `hosts_list` | List all saved hosts (optional tag filter) |
| `hosts_get` | Get full details for a host by ID |
## Data files
| Path | Description |
|------|-------------|
| `~/.shellport/hosts.json` | Saved host inventory |
| `~/.shellport/session.json` | Active session state |
## Project structure
```
shellport/
├── cmd/
│ ├── select/ TUI host selector
│ ├── ssh-watch/ SSH session monitor
│ └── mcp-server/ MCP protocol server
├── internal/
│ ├── model/ Shared types + validation
│ ├── store/ Disk I/O (hosts, sessions)
│ ├── ssh/ SSH args, binary discovery
│ ├── tui/ Interactive UI (bubbletea)
│ ├── mcp/ MCP protocol (JSON-RPC)
│ ├── session/ PTY monitoring + output parsing
│ └── safefile/ Symlink-safe file operations
├── lib/core/ Shell utilities (store, ui, base)
├── bin/ Shell subcommands (add, ls, show, edit, rm)
├── sshm Main CLI dispatcher (bash)
├── Makefile
└── go.mod
```
## Development
```bash
make build # build binaries
go test ./... -count=1 # run all tests
go test ./... -cover # run tests with coverage
go vet ./... # static analysis
make clean # remove built binaries
```
## License
MIT