SSH connection manager with MCP server for AI-assisted operations across servers.
Model Context Protocol (MCP) Server: io.github.danmartuszewski/hop
This MCP server provides an SSH connection manager for AI-assisted operations across servers. Its purpose is to reduce manual SSH command entry by enabling simpler commands like hop prod to connect, plus additional operations such as executing commands across matching server groups.
🛠️ Key Features
SSH connection management
MCP server for AI-assisted operations across servers
Command shortcuts like hop prod (fuzzy match any server)
Ability to run commands on multiple servers (e.g., hop exec production "uptime")
🚀 Use Cases
Interactive access to remote environments without typing long SSH options
Executing the same command across all servers in a group (e.g., prod servers)
⚡ Developer Benefits
Simplifies repeated SSH workflows by remembering less
Supports fuzzy server selection and group-based command execution
⚠️ Limitations
Provided information does not specify authentication details, supported OS/platforms, or full tool coverage beyond the shown examples.
Stop typing long SSH commands. Just hop prod and you're in.
hop TUI dashboard
Why hop?
bash
# Before: remembering and typing this every time
ssh -i ~/.ssh/work_key deploy@app-server-prod-03.us-east-1.example.com -p 2222
# After
hop prod
bash
hop prod # fuzzy match any server
hop exec production "uptime"# run command on all prod servers
hop import # import your existing ~/.ssh/config
hop # launch the TUI, manage everything
Install
Homebrew (macOS/Linux)
bash
brew install danmartuszewski/tap/hop
Go
bash
go install github.com/danmartuszewski/hop/cmd/hop@latest
From source
bash
git clone https://github.com/danmartuszewski/hop.git && cd hop && make build
./bin/hop
Install with an AI agent
Using Claude Code, Codex, Cursor, or another coding agent? Paste the block below into your agent and it will pick the right install path for your machine, register hop's MCP server, and verify the install.
text
Install hop on this machine and register its MCP server. Do the steps in order;
stop and report on the first failure.
1. Pick ONE install method, in this priority:
a. Homebrew (macOS or Linux):
brew install danmartuszewski/tap/hop
b. Go 1.22+ available:
go install github.com/danmartuszewski/hop/cmd/hop@latest
c. From source (no brew, no Go on PATH):
git clone https://github.com/danmartuszewski/hop.git && cd hop && make install
2. Verify the binary is on PATH:
hop version
3. Register the MCP server with whichever agent the user is running. Skip
clients the user does not use:
- Claude Code: claude mcp add hop -- hop mcp
- Codex CLI: codex mcp add hop -- hop mcp
- Claude Desktop / Cursor / Windsurf — add to the client's MCP config:
{ "hop": { "command": "hop", "args": ["mcp"] } }
4. (Optional) Seed the config from the user's existing SSH config. Preview
first; --yes is required for a non-interactive run:
hop import --dry-run
hop import --yes
5. Confirm hop's MCP tools are reachable from the agent (e.g. list_connections).
Constraints:
- Do NOT run bare `hop` — it launches an interactive TUI and will hang a
non-interactive session. Use subcommands (`hop version`, `hop list`, …).
- Do NOT modify ~/.ssh/config. hop reads it via `hop import` only.
- Do NOT commit secrets or identity files.
After step 3, restart the agent so it picks up the new MCP server.
Features
Fuzzy matching - Type hop prod to connect to app-server-prod-03
TUI dashboard - Browse, add, edit, delete connections with keyboard or mouse
SSH config import - Already have servers in ~/.ssh/config? Import them in one command
Export - Export filtered connections to YAML for sharing or backup
Multi-exec - Run commands across multiple servers at once
Groups & tags - Organize by project, environment, or custom tags
Jump hosts - ProxyJump support for bastion servers
Landing directory - Drop straight into a predefined working directory on connect
MCP server - Let AI assistants manage your servers — search connections, run commands, check status across projects
Mosh support - Use mosh instead of SSH for roaming and unreliable connections
version:1defaults:user:adminport:22# use_mosh: true # Uncomment to use mosh for all connectionsconnections:-id:prod-webhost:web.example.comuser:deployidentity_file:~/.ssh/work_key# Private key for this connectionremote_dir:/var/www/myapp# Land in this directory on connectproject:myappenv:productiontags: [web, prod]
-id:prod-dbhost:db.example.comuser:dbadminport:5432project:myappenv:productiontags: [database, prod]
-id:staginghost:staging.example.comuser:deployproject:myappenv:staging-id:private-serverhost:10.0.1.50user:adminproxy_jump:bastion# Connect via jump hostforward_agent:true# Forward SSH agent-id:remote-devhost:dev.example.comuser:danuse_mosh:true# Use mosh instead of SSHgroups:production: [prod-web, prod-db]
web-servers: [prod-web, staging]
Security note:forward_agent: true exposes your SSH keys to anyone with root access on the remote server. Only enable this for servers you fully trust. Consider using proxy_jump instead when you just need to reach internal hosts through a bastion.
Mosh Support
Mosh (mobile shell) is useful for connections over unreliable networks — it handles roaming, intermittent connectivity, and high latency gracefully.
Global default — enable mosh for all connections:
yaml
defaults:use_mosh:trueconnections:-id:remote-devhost:dev.example.com-id:legacy-serverhost:old.example.comuse_mosh:false# Override: use SSH for this one
Per-connection — enable mosh for specific connections:
One-off — use the --mosh flag without changing config:
bash
hop connect myserver --mosh
hop myserver --mosh
Per-connection use_mosh: false overrides the global default. SSH options (port, identity file, proxy jump, agent forwarding) are automatically passed to mosh via its --ssh flag. Mosh requires both the local mosh-client and mosh-server on the remote host.
Note:hop exec always uses SSH regardless of use_mosh, since mosh is designed for interactive sessions.
Landing Directory
Set remote_dir to have a connection drop you straight into a specific directory instead of $HOME:
yaml
connections:-id:prod-webhost:web.example.comuser:deployremote_dir:/var/www/myapp# cd here on connect-id:my-devhost:dev.example.comremote_dir:~/projects/api# ~ is expanded on the remote host
On connect, hop runs cd into the directory and then hands you a normal interactive login shell, so the session behaves exactly like a regular SSH login — just somewhere else. A few details worth knowing:
Absolute paths and ~ both work.~ and ~user are expanded by the remote shell.
Forgiving by design. If the directory is missing or inaccessible, you still land in a shell (in $HOME) rather than getting bounced off the host.
Works in new tabs too.hop open carries the landing directory into every terminal it launches.
Note:remote_dir is ignored when you pass an explicit command (e.g. hop connect web -- uptime or hop exec), since those aren't interactive sessions.
TUI Dashboard
Launch with hop or hop dashboard.
When you connect to a server from the dashboard (by pressing Enter), the SSH session starts, and the dashboard automatically returns after the session ends. This lets you quickly hop between servers without restarting the TUI each time.
For one-shot connections that exit to your terminal, use:
bash
hop <query> # fuzzy match and connect
hop connect <id> # connect by exact ID
Keyboard Shortcuts
Key
Action
↑/k
Move up
↓/j
Move down
PgUp/PgDn
Move by page
g
Go to top
G
Go to bottom
/
Filter connections (supports multi-keyword AND search)
t
Filter by tags
r
Toggle sort by recent
Enter
Connect to selected
a
Add new connection
i
Import from SSH config
p
Paste SSH string (quick add)
e
Edit selected
c
Duplicate selected (opens a prefilled copy)
d
Delete selected
x
Export connections to YAML
y
Copy SSH command
T
Open theme picker
?
Show help
q
Quit
Filtering Connections
Press / to filter connections by typing keywords. The filter supports multi-keyword AND logic - separate keywords with spaces to find connections matching all terms.
Examples:
prod - matches connections containing "prod"
prod web - matches connections containing both "production" AND "web"
kaf staging - matches connections with both "kafka" AND "staging"
The filter searches across connection IDs, hosts, projects, environments, and tags.
Press c on any connection to create a copy. The add form opens with every
field pre-filled from the original — including options that aren't shown in
the form, like proxy jump and mosh — and a collision-free ID suggestion (e.g.
web-prod → web-prod-copy). Adjust whatever you need and save. If you pick an
ID that already exists, the form stays open with your edits intact so you can
fix it.
Importing from SSH Config
Import existing connections from your ~/.ssh/config file:
From the dashboard: Press i to open the import modal, select which connections to import, and press Enter.
From the CLI:
bash
hop import # Import from ~/.ssh/config
hop import --dry-run # Preview what would be imported
hop import --file ~/.ssh/config.d/work # Import from custom path
What gets imported:
Host alias becomes the connection ID
HostName, User, Port, IdentityFile
ProxyJump for jump host connections
ForwardAgent setting
What gets skipped:
Wildcard patterns (Host *, Host *.example.com)
Entries without a HostName (alias is used as hostname)
Conflict handling: If a connection ID already exists, the imported connection is renamed with -imported suffix (e.g., myserver → myserver-imported).
Exporting Connections
Export a subset of connections to a YAML file for sharing, backup, or transferring to another machine.
From the dashboard: Press x to open the export modal. Only currently filtered connections are shown — apply text or tag filters first to narrow the selection. Toggle items with Space, then press Enter to save.
From the CLI:
bash
hop export --all # Export all to stdout
hop export --all -o backup.yaml # Export all to a file
hop export --project myapp -o myapp.yaml # Export by project
hop export --tag database # Export by tag
hop export --env production # Export by environment
hop export --id web-1,web-2 # Export specific connections
At least one filter flag or --all is required. Filters combine with AND logic.
Theming
The dashboard ships with sixteen color presets — each popular theme has both a dark and a light variant, listed separately so you can pick whichever you want regardless of your terminal background. Press T to browse them with live preview: ↑/↓ to navigate, Enter to save the choice into your config, Esc to revert.
Family
Dark
Light
Built-in hop
default-dark
default-light
Everforest
everforest-dark
everforest-light
Gruvbox
gruvbox-dark
gruvbox-light
Catppuccin
catppuccin-mocha
catppuccin-latte
Tokyo Night
tokyo-night-storm
tokyo-night-day
Solarized
solarized-dark
solarized-light
Nord
nord
nord-light
Dracula
dracula
alucard
Picking a preset writes a single line to your config:
yaml
theme_preset:everforest-dark
When theme_preset is unset, hop auto-picks default-dark or default-light based on your terminal background.
Custom overrides
Layer your own colors on top of any preset:
yaml
theme_preset:everforest-dark# optional; omit to auto-pick defaulttheme:# applies to every presetprimary:"#0066cc"theme_dark:# only applies when the preset is a dark variantselection:"#1f1f28"theme_light:# only applies when the preset is a light variantforeground:"#1c1f24"
Color values can be either a quoted ANSI 256 code ("39") or a hex string ("#bd93f9"). ANSI codes adapt to your terminal's palette; hex values are absolute.
Available keys: primary, secondary, accent, success, warning, error, muted, selection, foreground. Any key you don't set falls through to the preset, then to the built-in default.
CLI Commands
bash
hop # Open TUI dashboard
hop <query> # Fuzzy match and connect
hop connect <id> # Connect by exact ID
hop get <id> <field> # Print single field value to stdout
hop get <id> f1,f2,f3 # Print multiple fields tab-separated
hop get <id> # Print all fields as "key value" lines
hop get --help# Full field list and flags
hop list # List all connections
hop list --json # List as JSON
hop list --flat # Flat list without grouping
hop import # Import from ~/.ssh/config
hop import --file <path> # Import from custom path
hop import --dry-run # Preview without importing
hop export --all # Export all connections to stdout
hop export --project <name> # Export filtered connections
hop export --tag <tag> -o f # Export to file
hop open <target...> # Open multiple terminal tabs
hop exec <target> "cmd"# Execute command on multiple servers
hop resolve <target> # Test which connections a target matches
hop mcp # Start MCP server (read-only)
hop mcp --allow-exec # Start MCP server with remote exec
hop version # Show version
Targeting
Commands like exec and open accept a target that resolves to one or more connections. The target is matched in this order:
Named group — an explicit list of connection IDs defined under groups: in config
Project-env pattern — matches connections by project and env fields (e.g. myapp-prod matches all connections with project: myapp and env: prod)
Fuzzy match — falls back to fuzzy matching a single connection ID
You can also filter any target by tag with --tag.
Use hop resolve to preview which connections a target will match before running anything:
bash
hop resolve production # see what "production" resolves to
hop resolve "web*"# test a glob pattern
hop resolve myapp-prod --tag=web # combine target + tag filter
Examples
bash
# Fuzzy connect
hop prod # matches "prod-web", "prod-db", etc.
hop web # matches first *web* server# Multi-exec with different target types
hop exec production "uptime"# named group
hop exec myapp-prod "df -h"# project-env pattern
hop exec"web*""systemctl status"# glob pattern
hop exec --tag=database "psql -c '\\l'"# tag filter# Open multiple tabs
hop open production # named group
hop open web1 db1 api1 # specific IDs
hop open myapp-prod -- "htop"# with initial command# List connections
hop list --flat
Scripting with hop
hop get prints connection fields to stdout so you can drop them straight into shell pipelines and command substitutions — think of it as ssh -G for your hop config.
bash
# Build an ssh invocation from config:
ssh -i "$(hop get prod identity_file)""$(hop get prod user)@$(hop get prod host)"
bash
# Read multiple fields at once (tab-separated):
IFS=$'\t'read -r host port user < <(hop get prod host,port,user)
bash
# Fallback when a field is empty:
hop get prod port --default 22
bash
# Strict shells: suppress the trailing newline.
hop get prod host -n
bash
# Dump all non-empty scalar fields (ssh -G style "key value" lines):
hop get prod
bash
# Read a single SSH option by key:
hop get prod options.StrictHostKeyChecking
bash
# Structured output for jq and friends:
hop get prod host,port --json | jq -r .host
Matching is exact ID only (not fuzzy) — safer inside scripts. Unknown IDs exit 1 with a "did you mean" hint. See hop get --help for the full field list.
MCP Server (AI Assistant Integration)
hop includes a built-in Model Context Protocol server that lets AI assistants like Claude Code and Codex manage your servers directly. Ask your assistant to check disk space across production, restart a service on staging, or find which servers belong to a project — it discovers your connections, resolves targets, and executes commands through hop.
Setup
Claude Code:
bash
claude mcp add hop -- hop mcp
Codex CLI:
bash
codex mcp add hop -- hop mcp
Claude Desktop — add to your config (~/Library/Application Support/Claude/claude_desktop_config.json):
Or generate the Claude Desktop config automatically:
bash
hop mcp --print-client-config # read-only
hop mcp --print-client-config --allow-exec # with remote exec enabled
Tools
By default, only read-only tools are exposed:
Tool
Description
list_connections
List connections, filter by project/env/tag
search_connections
Fuzzy search across all connections
get_connection
Get details for a specific connection
resolve_target
Preview how a target pattern resolves
list_groups
List all named groups
get_history
Connection usage history
build_ssh_command
Build the full SSH command string
To enable remote command execution, start with --allow-exec:
bash
claude mcp add hop -- hop mcp --allow-exec
codex mcp add hop -- hop mcp --allow-exec
This adds the exec_command tool, which runs shell commands on matched servers with output limits (64KB/host, 50 hosts max).
Resources
The server also exposes browsable resources:
URI
Description
hop://config
Config summary (counts, projects, environments)
hop://connections
All connections
hop://connections/{id}
Individual connection details
hop://groups
All groups and members
Security
Identity files (SSH key paths) are never exposed through MCP
Remote execution is disabled by default and requires explicit --allow-exec
All logging goes to stderr to keep the JSON-RPC transport clean
Shell Completions
bash
# Bash (Linux)
hop completion bash | sudotee /etc/bash_completion.d/hop > /dev/null
# Bash (macOS with Homebrew)
hop completion bash > $(brew --prefix)/etc/bash_completion.d/hop
# Zsh (add to ~/.zshrc)source <(hop completion zsh)
# Fish
hop completion fish > ~/.config/fish/completions/hop.fish
Flags
bash
-c, --config <path> # Use custom config file
-v, --verbose # Verbose output
-q, --quiet # Suppress non-essential output
--dry-run # Print SSH command without executing
--mosh # Use mosh instead of SSH for this connection
Building
bash
make build # Build binary to ./bin/hop
make test# Run tests
make test-docker # Run tests in Docker (isolated)
make install # Install to $GOPATH/bin
make docker # Build Docker image
Docker
bash
# Build image
docker build -t hop .
# Run interactively
docker run -it --rm hop
# Run tests in container
docker build --target tester -t hop-test .
