List all SSH hosts registered in the inventory.

Returns the alias, hostname, port, username, and auth type for every configured host. Call this first when you don't know what machines are available.

Args: response_format: 'markdown' (default) for a readable table, or 'json' for structured data.

Returns: Formatted list of hosts, or a message if the inventory is empty.

Examples: - "What servers can I connect to?" -> ssh_list_hosts() - "Show me all SSH targets as JSON" -> ssh_list_hosts(response_format='json')

Register a new SSH host in the inventory.

Saves the host details to hosts.yaml so it can be referenced by alias in all other ssh_* tools. Supports key, password, and agent authentication.

Args: alias: Short nickname for the host (e.g., 'webserver', 'db-prod'). Only letters, digits, underscores, and hyphens are allowed. hostname: IP address or FQDN (e.g., '192.168.1.10', 'db.example.com'). username: SSH login username (e.g., 'ubuntu', 'ec2-user'). auth_type: Authentication method — 'key' (private key file), 'password', or 'agent' (ssh-agent). port: SSH port (default 22). key_path: Required when auth_type='key'. Path to the private key file (e.g., '~/.ssh/id_rsa'). key_passphrase: Optional passphrase to decrypt an encrypted private key. password: Required when auth_type='password'. description: Optional human-readable note about this server. overwrite: Set True to replace an existing host with the same alias.

Returns: Success message or error description.

Examples: - Add a key-based host: alias='webserver', hostname='10.0.0.5', username='ubuntu', auth_type='key', key_path='~/.ssh/id_rsa' - Add a password host: alias='legacy', hostname='old.corp.net', username='admin', auth_type='password', password='s3cr3t' - Add an agent-auth host: alias='jump', hostname='bastion.example.com', username='ops', auth_type='agent'

Remove a host from the SSH inventory permanently.

This only removes the local config entry — it does NOT touch the remote server in any way.

Args: alias: The host alias to remove.

Returns: Confirmation or error message.

Verify that a host is reachable and authentication succeeds.

Attempts to open an SSH session and run a trivial echo command. Use this immediately after ssh_add_host to confirm your credentials are correct.

Args: alias: Host alias to test (must exist in inventory).

Returns: '✓ Connected …' on success, or an actionable error on failure.

Examples: - After adding a new host: ssh_test_connection(alias='webserver') - Debugging a connection issue: ssh_test_connection(alias='db-prod')

Execute a shell command on a remote SSH host and return the output.

The command runs in the login user's default shell. Both stdout and stderr are captured and returned. The exit code is included so you can detect failures.

Args: alias: Target host alias. command: Shell command to execute (e.g., 'ls -la /var/log', 'systemctl status nginx', 'df -h'). timeout: Maximum seconds to wait (default 60, max 3600). env: Optional extra environment variables dict for this command. cwd: Remote working directory. When set the effective invocation becomes 'cd && '. Use absolute POSIX paths (e.g. '/var/www/html'). State is NOT persisted between calls. sudo_password: When set, the command runs via sudo. The password is never echoed back in output. response_format: 'markdown' (default, human-readable) or 'json'.

Returns: Command output (stdout + stderr) with exit code.

Examples: - Inspect disk usage: command='df -h' - Check a service: command='systemctl status nginx' - Tail logs: command='tail -n 50 /var/log/syslog' - Install a package: command='sudo apt-get install -y htop'

Read the contents of a file on a remote SSH host.

Uses SFTP to transfer the file. Suitable for config files, logs, scripts, etc. For binary files set encoding='raw' to get a base64-encoded string.

Args: alias: Host alias. remote_path: Absolute path of the file to read on the remote host (e.g., '/etc/nginx/nginx.conf'). encoding: Text encoding to decode the file (default 'utf-8'). Use 'raw' to get a base64-encoded string for binary files.

Returns: File contents as text, or base64-encoded bytes for encoding='raw'. Returns an error string on failure.

Examples: - Read nginx config: alias='web', remote_path='/etc/nginx/nginx.conf' - Read /etc/hosts: remote_path='/etc/hosts' - Read binary file: remote_path='/usr/bin/ls', encoding='raw'

Write content to a file on a remote SSH host (create or overwrite).

Uses SFTP to transfer the content. Missing parent directories are created automatically. For binary content, base64-encode it and set encoding='base64'.

Args: alias: Host alias. remote_path: Absolute destination path on the remote host. content: Text to write. For binary content, encode as base64 and set encoding='base64'. encoding: 'utf-8' to write the content as text (default), 'base64' to decode first.

Returns: Success message with byte count, or an error description.

Examples: - Write a cron job: remote_path='/etc/cron.d/myjob', content='...' - Deploy a config: remote_path='/etc/myapp/config.yaml', content='...' - Write a script: remote_path='/usr/local/bin/deploy.sh', content='...'

List the contents of a directory on a remote SSH host.

Returns file names, types, sizes, permissions, and last-modified timestamps. Directories are listed before files, both sorted alphabetically.

Args: alias: Host alias. remote_path: Directory path to list (default '~' = home directory). limit: Maximum number of entries to return. Useful for large directories like /proc or /var/log. Omit to return all entries. response_format: 'markdown' (default) or 'json'.

Returns: Directory listing with columns: Type | Name | Size | Permissions | Modified. JSON format: {path, total, count, truncated, entries: [{name, type, size, permissions, modified}]}

Examples: - Browse home dir: ssh_list_directory(alias='web') - List /var/log: remote_path='/var/log' - List /etc/nginx: remote_path='/etc/nginx'

Return OS, home directory, cwd, and path style of the machine running the MCP server.

Call this before ssh_upload_file or ssh_download_file to discover the correct local_path format (Windows backslash vs POSIX forward-slash).

Args: response_format: 'json' (default) or 'markdown'.

Returns: OS info including: os, home, cwd, path_style ('windows' or 'posix').

Examples: - Before uploading: ssh_get_local_info() → learn that local_path needs Windows format - Debugging path errors: confirm the server's working directory

Upload a local file to a remote SSH host via SFTP.

The remote parent directory is created automatically if it doesn't exist. Use this to deploy configs, binaries, or any large file.

Args: alias: Target host alias. local_path: Absolute path to the local file to upload, in the format native to the machine running the MCP server (e.g. 'C:\Users\me\file.txt' on Windows, '/home/me/file.txt' on Linux/macOS). Call ssh_get_local_info first if you are unsure which format to use. remote_path: Absolute POSIX destination path on the remote host (e.g. '/home/user/file.txt').

Returns: Success message with byte count, or an error description.

Examples: - Deploy an app binary: local_path='/dist/myapp', remote_path='/opt/myapp/bin/myapp' - Upload a TLS cert: local_path='/tmp/server.crt', remote_path='/etc/ssl/certs/server.crt'

Download a file from a remote SSH host to the local machine via SFTP.

The local parent directory is created automatically if needed.

Args: alias: Source host alias. remote_path: Absolute POSIX path of the file on the remote host. local_path: Absolute destination path on the local machine, in the format native to the machine running the MCP server (e.g. 'C:\Users\me\downloads\file.txt' on Windows, '/home/me/downloads/file.txt' on Linux/macOS). Call ssh_get_local_info first if you are unsure which format to use.

Returns: Success message with byte count, or an error description.

Examples: - Fetch a log: remote_path='/var/log/app.log', local_path='/tmp/app.log' - Pull a DB dump: remote_path='/backups/db.sql.gz', local_path='/tmp/db.sql.gz'