cygnus-ssh-mcp

Retrieves a list of all available tools on this MCP server, along with their descriptions. Returns: A list of dictionaries, where each dictionary contains the 'name' and 'description' of an available tool.

Create a compressed archive from a directory. IMPORTANT cross-platform caveat: on Windows, `tar.gz`/`tar` are NOT natively available - requesting either one silently creates a `.zip` file instead (via `Compress-Archive`), and `archive_path`'s extension is auto-corrected to `.zip` if needed. The only way to tell this happened is the returned `format` field saying `'zip'` even though you asked for `tar.gz`/`tar`. An archive created this way on Windows can only be extracted with ssh_archive_extract on another Windows host - Linux/macOS's extractor only recognizes `.tar`/`.tar.gz`/`.tgz` files, not `.zip`. There is no cross-platform-portable archive format currently available through this tool. Returns: On success: `{'status': 'success', 'success': True, 'archive_created' (the actual path used, which may differ from `archive_path` if the extension was corrected on Windows), 'format' (the ACTUAL format used - 'tar.gz'/'tar' on Linux/macOS, always 'zip' on Windows), 'size_bytes'}`. On failure: `{'status': 'error', 'message': str}` - not a raised exception.

Extract an archive to a directory. The accepted format is platform-specific and determined purely by `archive_path`'s file extension (not by inspecting the archive's actual content): - Linux/macOS: `.tar.gz`, `.tgz`, or `.tar` only. A `.zip` file (e.g. created by ssh_archive_create on Windows) will fail here with an unsupported-format error. - Windows: `.zip` only. A `.tar`/`.tar.gz` file (e.g. created by ssh_archive_create on Linux/macOS) will fail here the same way. There is no cross-platform-portable archive format currently available through this tool - archives must be created and extracted on the same OS family. `overwrite=False` (default) does not fail outright if some files already exist at the destination - on Linux/macOS it extracts everything else and just logs a warning about the skipped files (no per-file detail returned); on Windows the behavior follows `Expand-Archive`'s own overwrite handling. On a 'linux'/'flex' connection with a BusyBox-style `tar` (check `ssh_conn_connect`/`ssh_conn_host_info`'s `capabilities`), this can raise a clear error instead of running - unlike the wrong-format/extraction-error cases below, which return an error dict, this is a raised exception. Two independent gaps: missing `--strip-components` blocks extraction entirely (no clean single-tool fallback - extract without stripping via `ssh_cmd_run`, the archive's own top-level directory will remain, then relocate its contents up one level yourself); missing `--keep-old-files` only blocks when `overwrite` isn't explicitly `True` - passing `overwrite=True` avoids that one specifically. Returns: On success: `{'status': 'success', 'success': True, 'extracted_files': [str, ...] (paths as listed inside the archive), 'destination_path'}`. On failure (wrong format for this platform, extraction error): `{'status': 'error', 'message': str, 'extracted_files': []}` - not a raised exception.

Wait for the specified duration, then check the status of a command started with ssh_cmd_run. Call this repeatedly - it's designed to be polled - after ssh_cmd_run returns status='io_timeout' or 'wait_timeout' (the remote command is still genuinely running in both cases - background monitoring keeps collecting its output/exit code), until you get a TERMINAL status below. Do not rerun the original command while polling. Terminal status values (nothing left to wait for, stop polling): - 'completed': confirmed finished, exit_code is populated - including for commands that survived an io_timeout/wait_timeout, since background monitoring keeps watching for the real exit code. - 'killed': the remote process was confirmed terminated (e.g. runtime_timeout killed it, or a prior ssh_cmd_kill call found it already gone) - exit_code is not known. - 'completed_exit_code_unknown': rare fallback - monitoring stopped without a confirmed exit code (should only really happen from before background monitoring existed, or after an unexpected error) and a live check now confirms the remote process is no longer running. Only its output (via ssh_cmd_output) is available, not its exit code. Non-terminal status values (keep polling): - 'running': still being actively monitored, not yet finished. - 'unknown_still_running': rare fallback (same caveat as 'completed_exit_code_unknown') where a live check confirms the remote command is still actually running. Not a failure - call this tool again to keep checking. Other: - 'not_found': the handle_id doesn't exist (may be from a previous connection - handles don't survive reconnects, but background task PIDs from ssh_task_launch do). - 'unknown': the handle exists but its metadata is missing from history (rare, internal inconsistency) - treat like 'not_found'. Fallback behavior: if `handle_id` doesn't match any ssh_cmd_run handle, this tool also tries treating it as a raw background-task PID (same as ssh_task_status) and, if that succeeds, returns `{'pid', 'status': 'running'/'exited'/'invalid'/'error', 'is_background_task': True, ...}` instead - a DIFFERENT status vocabulary than the one above. Prefer ssh_task_status directly for PIDs to avoid ambiguity. Returns: `{'handle_id', 'waited_seconds', 'status', 'exit_code', 'pid', 'output_available', 'output_lines', 'timestamp'}`, plus `'next_step'` (guidance text) when `status` is non-terminal.

Clear the command history for the current SSH connection. Returns: Dictionary with operation status

Retrieve command execution history with optional output snippets. Returns: List of dictionaries containing command history, ordered from oldest to newest by default. Each entry contains: - id: Command handle ID - command: Executed command - exit_code: Exit status - start_time: Execution start timestamp - end_time: Execution end timestamp - origin: 'user' for a directly user-requested command, or an internal-plumbing label ('tool_internal', 'connection_probe', 'sudo_probe') for a helper command issued by another tool - parent_tool: Name of the MCP tool that triggered this command, when origin != 'user' - output: Stdout snippet (if include_output=True) - stderr is NOT included here, even for a failed command; see the separate 'stderr' field - stderr: Stderr snippet (if include_output=True) - often the more useful stream for a failed command; retrieved the same way ssh_cmd_output(stream='stderr') would

Terminate a currently running command by its handle ID (the `id` field from ssh_cmd_run's response). This tool is specifically for killing commands started with ssh_cmd_run - it looks up `handle_id` in this connection's command history, not by raw PID. For background tasks launched with ssh_task_launch, use ssh_task_kill with the PID instead. Raises an error if `handle_id` doesn't exist in history (e.g. from a previous connection - handles don't survive reconnects) or has no associated PID. If force=True and the process doesn't exit after wait_seconds, it will be forcibly killed with SIGKILL (signal 9). Returns: `{'handle_id', 'pid', 'result', 'signal', 'force_kill_used', 'timestamp'}`. `result` is one of: - 'not_running': the command was already confirmed not running before any signal was sent (checked first, via a live PID status check) - nothing to do. - 'killed': confirmed terminated (by the signal or the force-kill fallback - see `force_kill_used` to tell which). - 'already_exited': the process was gone by the time the signal landed. - 'failed_to_kill': still running after the signal (and force-kill, if `force=True`) - not terminal, the process is still alive. - 'invalid_pid': the command's tracked PID wasn't a valid positive integer. - 'error': the kill attempt itself failed unexpectedly - the process's real state is unknown. `force_kill_used` is True iff the SIGKILL fallback was actually attempted (the initial signal alone was not enough), regardless of whether the fallback itself succeeded - False if the initial signal alone was sufficient, the process was already gone, or `force=False`. Note: after a successful kill (`'killed'` or `'already_exited'`, or the early `'not_running'` case), a later `ssh_cmd_check_status` call for this same `handle_id` will report status `'killed'`.

Retrieve captured output from a command started with ssh_cmd_run, identified by its handle_id. Useful after an io_timeout/wait_timeout to see progress so far - including output produced after that call returned, since background monitoring keeps collecting it - or any time to re-inspect an earlier command's output without rerunning it. stdout and stderr are captured in separate buffers, not interleaved - `stream` picks which one to retrieve. ssh_cmd_run's own response only ever includes `output` (stdout); to see stderr from a successful command (warnings, progress meters, non-fatal messages - stderr on success is real output, not just for failures), call this tool with `stream='stderr'`. Raises an error if handle_id doesn't exist (e.g. from a previous connection - handles don't survive reconnects). Returns: A plain list of output lines from the selected stream (most recent `lines`, or the last 50 by default) - not a dict, no status/metadata. For total line counts and whether output was truncated, use ssh_cmd_history(include_output=True) instead (stdout only there).

Execute a command on the remote host and BLOCK until it completes, an io_timeout (silence), a wait_timeout (elapsed cap), or a runtime_timeout (hard cap) occurs. Timeout semantics (read this before choosing values): - io_timeout and wait_timeout firing do NOT mean the remote command stopped - it genuinely keeps running. Monitoring is handed off to a background thread so output/exit code continue to be collected; the response has status='io_timeout'/'wait_timeout', still_running=true, and an id/pid you can use with ssh_cmd_check_status(handle_id=...) to poll again later, or ssh_cmd_output(handle_id=...) to read output collected so far (including output produced after this call returned). Do not rerun the command. You can also still decide to end it early with ssh_cmd_kill(handle_id=...) at any point after either of these fires. - io_timeout fires only on SILENCE (no output for N seconds) - a command that keeps producing output never triggers it, however long it runs. - wait_timeout fires after N seconds of TOTAL elapsed wait, regardless of activity - use this if you want to check in periodically on a long-running command even while it's actively producing output, rather than being blocked until completion. - runtime_timeout is the only knob that DOES attempt to terminate the remote command - a hard safety ceiling, not a UX mechanism. Set it generously (much longer than the command should ever realistically take). - For commands that should survive you disconnecting/reconnecting entirely (not just this call returning), use ssh_task_launch instead - it runs fully detached from this SSH session, whereas a command started here (even after surviving io_timeout/wait_timeout) is still tied to the current connection's lifetime. You can access command history using 'ssh_cmd_history' to see previous commands and their output. Commands run this way always appear there with origin='user' - pass include_internal=False to ssh_cmd_history to hide unrelated internal plumbing from other tools (e.g. ssh_file_write's sudo dance). Working directory: each call is an independent remote process (like a GitHub Actions step or Ansible task, not a continuous shell) - nothing is remembered between calls, including 'cd'. Running ssh_cmd_run("cd /var/log") does NOT affect a later ssh_cmd_run("ls"); it will still list the login directory. Use absolute paths, chain "cd dir && command" within one call, or pass the cwd parameter to run this specific call in a specific directory (Linux/macOS only for now). Returns: Dictionary containing command output, status, and metadata. The handle identifier is returned here as `'id'`, but every other tool that accepts it (ssh_cmd_check_status, ssh_cmd_kill, ssh_cmd_output) names the same parameter `handle_id` - pass this value there. `output` (stdout) and `stderr` are always two SEPARATE fields, never interleaved into one combined stream - a command that succeeds can still have written to stderr (warnings, progress meters, non-fatal messages), so check `stderr` even on `status='success'`. `status` is one of: - 'success': command completed with exit code 0. `exit_code`, `output`, `stderr` populated. - 'command_failed': completed with a non-zero exit code. `exit_code`, `output`, `stderr` populated. - 'cwd_not_found': the `cwd` parameter didn't exist on the remote host - the command was NOT executed at all (fails closed). - 'io_timeout': no output within `io_timeout` seconds - remote command was NOT killed, still_running=true. Poll with ssh_cmd_check_status(handle_id=...). - 'wait_timeout': `wait_timeout` elapsed regardless of activity - remote command was NOT killed, still_running=true. Poll with ssh_cmd_check_status(handle_id=...). - 'runtime_timeout': `runtime_timeout` exceeded - an attempt was made to kill the remote command (see ssh_cmd_check_status's `'killed'` status to confirm). - 'sudo_required': `use_sudo=True` but elevation isn't available (see ssh_conn_verify_sudo before retrying). - 'busy': another ssh_cmd_run is already in flight on this connection - only one command can run at a time per connection. - 'error': unexpected failure (e.g. connection dropped).

Add a new host configuration to the host configuration TOML file. Despite the name, this does NOT update an existing entry - if the `user@host` key already exists, this returns an error response (`{'status': 'error', ...}`, not a raised exception) rather than overwriting it; use ssh_host_update for that instead. Before calling this, check 'ssh_host_list' - the host you want may already be configured, in which case you can call 'ssh_conn_connect' directly without adding anything. Authentication requires either a password OR a keyfile (or both): - Password authentication: Provide `password` - Key-based authentication: Provide `keyfile` (and optionally `key_passphrase` if the key is encrypted) If using key-only authentication and sudo operations are needed, you must explicitly provide `sudo_password` unless the server has passwordless sudo configured. Warn the user that credentials will be visible to the LLM and that it would be better for the user to add the host directly in the host configuration file. That said, never read this file yourself (directly or via any file/shell tool) to look up, verify, or copy existing hosts' credentials - ssh_host_list, ssh_conn_add_host, ssh_host_update, ssh_host_remove, and ssh_host_use_config are the only tools you should need for host management, and none of them ever expose a stored password/passphrase back to you. This tool always adds to whichever config file is currently active (the server's default unless ssh_host_use_config was called to switch to an alternate one - check ssh_host_list's `config_path` if unsure). The host config file is `~/.mcp_ssh_hosts.toml` if it exists, otherwise `./mcp_ssh_hosts.toml` in the server's working directory - it stores every host's password, sudo password, and key passphrase in plaintext, which is exactly why the tools above exist instead of editing it by hand. The configuration is stored under a ["user@host"] key. Optional fields: - alias: A short name for connecting (e.g., 'prod' instead of '[email protected]') - description: A text description of what the host is for Returns: On success: `{'status': 'success', 'message', 'key', 'host', 'user', 'port', 'auth_method' ('key' or 'password'), and 'alias'/'description'/'keyfile' if provided}`. On failure (missing auth, duplicate host key, or duplicate alias): `{'status': 'error', 'error': <message>}` - for a duplicate host key, also includes `'existing_config'` (the current host/user/port/alias/description) so you can decide whether to use it as-is via `ssh_conn_connect` instead.

Establish an SSH connection using a pre-configured host. The host can be specified by its 'user@hostname' key or by its alias. Beyond the three fully-supported platforms (Linux, macOS, Windows), any other SSH target that responds to a basic shell command connects too, reported as os_type='flex' (e.g. FreeBSD/OPNsense/pfSense-style routers, or other unrecognized POSIX kernels). For 'linux' and 'flex' connections, a one-time capability probe checks the specific shell/coreutils features this server depends on (some embedded/BusyBox-based devices lack GNU extensions like `find -printf` or `tar --strip-components`) - the result is returned as 'capabilities' (raw probe results) and, if anything's missing, 'capability_warnings' (plain-English gaps). Tools that need a missing capability fail with a clear error naming what's missing, rather than a cryptic remote command failure - nothing is silently degraded. Returns: Dictionary with connection status and detailed system information. 'capabilities'/'capability_warnings' are included for 'linux'/'flex' connections only (empty/omitted for macOS/Windows, which are already fully supported and not probed).

Get detailed SSH connection status and system information. Returns: Dictionary containing full connection status and detailed system info including hardware, memory, disk usage, and more. For a 'linux' or 'flex' (non-Linux/macOS/Windows) connection, also includes 'capabilities' (probed GNU/BusyBox-coreutils feature support) and 'capability_warnings' (plain-English list of confirmed gaps) - see ssh_conn_connect's docstring for what these mean.

Check if there is an active SSH connection. Returns: bool: True if an active connection exists, False otherwise.

Get essential SSH connection status information. Returns: Dictionary containing basic connection status (user, working directory, OS type)

Check whether elevated access is available on the remote system, without running any privileged command. Call this before using `use_sudo=True` on other tools if you're not sure elevation will succeed. On Linux/macOS: probes whether `sudo` is available and whether it needs a password (via a passwordless `sudo -n` check, then a password-based check if that fails). Tools called afterward with `use_sudo=True` will use whichever mode this detected. On Windows: there is no per-command elevation - checks whether the current SSH session itself is already running as Administrator. If it's not, no tool call can become elevated; you must reconnect as an Administrator account instead. Returns: Dictionary with: - available (bool): True if sudo/elevation can be used at all (passwordless OR password-based on Linux/macOS; same as `passwordless` on Windows, since there's no separate password-based mode there) - passwordless (bool): True if no password is needed (passwordless sudo, or an already-elevated Windows session) - requires_password (bool): True if sudo works but needs a password (always False on Windows)

Recursively find and delete files matching a filename glob pattern (same pattern syntax as ssh_dir_search_glob, e.g. `*.tmp`) under a directory. `dry_run` DEFAULTS TO `True` - calling this with no arguments other than `path`/`pattern` only PREVIEWS which files would be deleted and deletes NOTHING; you must explicitly pass `dry_run=False` to actually delete. On a 'linux'/'flex' connection with a BusyBox-style `xargs` that doesn't support `-0` (check `ssh_conn_connect`/`ssh_conn_host_info`'s `capabilities`), this raises a clear error instead of running. Fallback: `ssh_cmd_run` with `find <path> -name '<pattern>' -exec rm -f {} +` instead - portable, and still safe with spaces in filenames. Returns: `{'status': 'success'/'error', 'deleted_files': [str, ...] (matching file paths that were/would be deleted)}`, plus `'dry_run': True` ONLY when this was a preview (check for this key to tell a preview apart from a real deletion) and `'error'` (string) on failure. Note the key is `deleted_files` here, vs. `deleted_items` on ssh_dir_delete.

Calculate the total size of a directory recursively (sum of all file sizes under it). On a 'linux'/'flex' connection with a BusyBox-style `du` that doesn't support `-s`+`-b` combined (check `ssh_conn_connect`/`ssh_conn_host_info`'s `capabilities`), this raises a clear error instead of running. Fallback: `ssh_cmd_run("du -sk <path>")` - kilobytes instead of exact bytes, but works on most BusyBox `du` builds even when `-sb` doesn't. Returns: `{'path', 'size_bytes' (int), 'size_human' (e.g. "1.23 MB", "512.00 KB", "3.50 GB" - 2 decimal places, binary/1024-based units)}`.

Copy a directory recursively (remote-to-remote; for local<->remote use ssh_dir_transfer instead). `overwrite` controls what happens if `destination_path` already exists: - `True`: the entire existing destination directory is deleted first, then a fresh copy is made. - `False` (default): does NOT block the copy - it copies into the existing destination as-is, merging with whatever's already there, and any file that shares a name with a source file gets silently overwritten anyway. This does NOT behave like the "fail if destination exists" semantics of ssh_file_move/ssh_file_copy's own `overwrite` parameter. Returns: `{'status': 'success'/'error', 'files_copied' (int), 'bytes_copied' (int), 'destination_path'}` (plus `'message'` on error). Note: `files_copied`/ `bytes_copied` are computed by counting the destination directory's TOTAL contents *after* the copy, not just the files newly copied in this call - if merging into a non-empty destination, these counts include pre-existing files too.

Delete a directory and all its contents recursively. `dry_run` DEFAULTS TO `True` - calling this with no arguments other than `path` only PREVIEWS what would be deleted and deletes NOTHING; you must explicitly pass `dry_run=False` to actually delete. Refuses to delete a small set of critical paths outright (root, home directory, `C:\Windows`, `C:\Users`, etc.) regardless of `dry_run`. For a simpler non-recursive removal without the preview step, see ssh_dir_remove. Returns: `{'status': 'success'/'error', 'deleted_items': [str, ...] (paths that were/would be removed, depth-first order)}`, plus `'dry_run': True` ONLY when this was a preview (check for this key to tell a preview apart from a real deletion - it's absent, not `False`, on actual deletions) and `'error'` (string) on failure. Also fails (with `'error'` set) if `path` is a recognized critical directory.

List contents of a directory recursively with full metadata (size, permissions, ownership, modification time) - use this instead of ssh_dir_list_files_basic (which only returns bare filenames, non-recursive) when you need more than just names, or ssh_dir_search_glob when you only need to filter by filename pattern without full metadata (that tool is also faster for large trees). `max_depth` uses standard `find -maxdepth` semantics: `max_depth=1` means `path` itself plus its immediate children only; omit for unlimited recursion. On a 'linux'/'flex' connection with a limited BusyBox-style `find` (no `-printf` - check `ssh_conn_connect`/`ssh_conn_host_info`'s `capabilities`), this raises a clear error instead of running. Fallback: `ssh_dir_list_files_basic` (non-recursive filenames) plus `ssh_file_stat` per entry for metadata - both are SFTP-based and unaffected by this, at the cost of one call per directory level. Returns: List of `{'path', 'type', 'size_bytes' (int), 'modified_time' (float Unix timestamp), 'permissions' (string, e.g. "755"), 'user', 'group'}`. `type` is a spelled-out word here ('file'/'directory'/'symlink'/'pipe'/'socket'/ 'block'/'character') - note this differs from ssh_dir_search_glob, which returns single-character type codes ('f'/'d'/'l') for the same concept. On Windows, `permissions` is always the literal placeholder `"0"` (Windows has no Unix-style permission bits) and `group` is always `"unknown"` - `user` still reflects the real file owner there.

List the immediate contents of a directory (via SFTP - not recursive, no metadata). For recursive listing with size/permissions/type/etc., or to filter by filename pattern, use ssh_dir_list_advanced or ssh_dir_search_glob instead. Returns: List of bare filenames (strings) directly inside `path` - not full paths, not recursive, and no indication of which entries are files vs. directories (use ssh_file_stat on an entry, or ssh_dir_list_advanced, if you need that).

Create a directory on the remote system. Parent-directory creation and `mode` behavior differ by platform/sudo: - Linux/macOS, `use_sudo=False` (default): uses SFTP `mkdir`, which is NOT recursive - this FAILS if the parent directory doesn't already exist. `mode` applies to the created directory. - Linux/macOS, `use_sudo=True`: uses `mkdir -p -m <mode>`, which DOES create any missing parent directories. - Windows: always creates missing parent directories (`New-Item -Force`, regardless of `use_sudo`, which has no effect on Windows anyway). The `mode` parameter is IGNORED entirely on Windows - there's no equivalent to Unix octal permissions there. Returns: `{'status': 'success', 'path', 'mode' (octal string - reflects the requested mode even on Windows, where it was actually ignored), 'message', 'connection'}` on success. Raises an exception on failure (e.g. missing parent directory without sudo on Linux/macOS).

Remove a directory on the remote system - this is the simple `rmdir`/`Remove-Item` equivalent. There is NO dry-run/preview mode here (unlike ssh_dir_delete below) - it acts immediately. If `recursive=False` (default) and the directory is not empty, this RAISES an exception rather than returning an error dict - it does not partially delete anything. For a safer recursive delete with a preview step, use ssh_dir_delete instead, which defaults to `dry_run=True` and returns a graceful `{'status': 'error', ...}` on failure instead of raising. Returns: `{'status': 'success', 'path', 'recursive', 'message', 'connection'}` on success. Raises an exception on failure (non-empty directory with `recursive=False`, path not found, permission denied, etc.) rather than returning an error dict.

Recursively search file CONTENTS for a pattern under a directory (unlike ssh_dir_search_glob/ssh_file_find_lines_with_pattern, which match filenames or search within a single already-known file respectively). Regex flavor differs by platform when `regex=True`: POSIX extended regex (`grep -E`) on Linux/macOS - avoid PCRE-only syntax like `\d`, use `[0-9]` or `[[:digit:]]` instead; Python's `re` module on Windows (matched locally after an SFTP read per file, not via PowerShell - see below). When `regex=False` (default), the pattern is matched as a literal fixed string. On Windows, filenames are enumerated via PowerShell but each file's content is read via SFTP and matched locally in Python, rather than piping matched line content back through PowerShell/Select-String - that content could otherwise come back corrupted for non-ASCII text, since Windows' console encodes stdout in its OEM code page rather than UTF-8 (the same problem ssh_file_read's SFTP approach avoids). On a 'linux'/'flex' connection with a BusyBox-style `xargs` that doesn't support `-0` (check `ssh_conn_connect`/`ssh_conn_host_info`'s `capabilities`), this raises a clear error instead of running. Fallback: `ssh_cmd_run` with `find <dir_path> -type f -exec grep -l '<pattern>' {} +` instead - portable, and still safe with spaces in filenames. Returns: List of `{'file': str, 'line': int, 'content': str}` - one entry per matching line, across all files under `dir_path`. Empty list if nothing matches (not an error).

Recursively search for files (or directories, with `include_dirs=True`) matching a filename glob pattern (e.g. `*.log`) - matches by NAME only, not content; use ssh_dir_search_files_content instead to search inside files. For metadata beyond just path/type (size, mtime, permissions), use ssh_dir_list_advanced instead. `max_depth` uses standard `find -maxdepth` semantics: this is the same on both Linux/macOS and Windows despite the different underlying commands. `max_depth=1` means the given `path` itself plus its immediate children only (not grandchildren); omit `max_depth` for unlimited recursion. On a 'linux'/'flex' connection with a limited BusyBox-style `find` (no `-printf` - check `ssh_conn_connect`/`ssh_conn_host_info`'s `capabilities`), this raises a clear error instead of running. Fallback: `ssh_dir_list_files_basic` (non-recursive filenames, match the pattern yourself) - SFTP-based and unaffected by this, at the cost of one call per directory level. Returns: List of `{'path': str, 'type': str}` - `type` is a single-character code (`f`=file, `d`=directory, `l`=symlink) from the underlying `find`/`stat` output, not a spelled-out word.

Transfer directories between local and remote systems. Uses archive-based transfer for efficiency: - Upload: Archives locally, transfers, extracts on remote - Download: Archives on remote, transfers, extracts locally Archive format is automatically selected based on remote OS: - Linux/macOS: tar.gz - Windows: zip

Copy a file on the remote host (source and destination are both remote paths - for local<->remote transfers use ssh_file_transfer instead). If `append_timestamp=True`, a timestamp is inserted before the destination's file extension in the format `%Y%m%dT%H%M%S`, e.g. `destination_path="/etc/hosts.bak"` becomes `/etc/hosts.20260704T153045.bak` - not appended after the extension, and not configurable to a different format. Returns: On success: `{'success': True, 'copied_to': <actual destination path used, including the timestamp if applied>}`. On failure (source not found, permission error): `{'success': False, 'error': str}` - not a raised exception.

Delete a line by its exact content. `match_line` must match EXACTLY ONE line in the file (whitespace-trimmed, literal text - not a pattern); if it matches zero lines or more than one, the operation fails with a descriptive error rather than guessing which line(s) to delete. Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique. (Equivalent to ssh_file_replace_line_multi(new_lines=[]), provided as a clearer-named shortcut.) Returns: On success: `{'success': True}` (no count field - only ever deletes the one matched line). On failure (match not found, match not unique, file not found/unreadable): `{'success': False, 'error': str}` - not a raised exception.

Search for a pattern in a remote file and return matching lines with their line numbers. Use this to find WHERE a pattern occurs before using ssh_file_get_context_around_line to see surrounding lines, or ssh_file_replace_line/ssh_file_delete_line_by_content to edit (those require an exact, unique line match - this tool helps you find that exact line first). Regex flavor differs by platform when `regex=True`: POSIX extended regex (`grep -E`) on Linux/macOS - avoid PCRE-only syntax like `\d`, use `[0-9]` or `[[:digit:]]` instead; Python's `re` module on Windows (matched locally after an SFTP read, not via PowerShell - see below). When `regex=False` (default), the pattern is matched as a literal fixed string on every platform. On Windows, this reads the whole file via SFTP and matches locally in Python, rather than shelling out to PowerShell/Select-String - matched line content could otherwise come back corrupted for non-ASCII text, since Windows' console encodes stdout in its OEM code page rather than UTF-8 (the same problem ssh_file_read's SFTP approach avoids). Returns: `{'total_matches': int, 'matches': [{'line_number': int, 'content': str}, ...]}`. No matches is not an error - `total_matches` is 0 and `matches` is `[]`. On failure (e.g. file not found, permission denied), an `'error'` key is present instead.

Get lines before and after a line, to see it in context before editing. Like the line-editing tools (ssh_file_replace_line and siblings), `match_line` must match exactly one line in the file (whitespace-trimmed, literal text, not a pattern) - use ssh_file_find_lines_with_pattern first if you're not sure the line is unique. Reads the file via SFTP and matches locally (same as ssh_file_find_lines_with_pattern) - Unicode/non-ASCII content is safe on all platforms, including Windows. Returns: On a unique match: `{'match_found': True, 'match_line_number': int, 'context_block': [{'line_number': int, 'content': str}, ...]}` (the matched line plus `context` lines before/after). If the line isn't found, or matches more than once: `{'match_found': False, 'error': str}` - for a multi-match error, also includes `'matches'` (every matching line, so you can pick a more specific `match_line`).

Insert one or more new lines immediately after a matching line. `match_line` must match EXACTLY ONE line in the file (whitespace-trimmed, literal text - not a pattern); if it matches zero lines or more than one, the operation fails with a descriptive error rather than guessing. Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique. PARAMETERS: * file_path: Path to the file to modify * match_line: Exact line content to match (whitespace-trimmed) * lines_to_insert: List of lines to insert after the match - To insert multiple lines: use ["first line", "second line", ...] - To insert a single line: use ["line to insert"] - To insert an empty line: use [""] * use_sudo: Use sudo for the operation (default: false) * force: Force operation even if file can't be read (sudo only) (default: false) RETURNS: On success: `{'success': True, 'lines_inserted': <len(lines_to_insert)>}` (note: the key is `lines_inserted` here, vs. `lines_written` on ssh_file_replace_line/ssh_file_replace_line_multi). On failure (match not found, match not unique, file not found/unreadable): `{'success': False, 'error': str}` - not a raised exception. Does NOT return `file_path` in the response. EXAMPLES: Example 1: Insert configuration lines after a marker ```json { "file_path": "/etc/nginx/nginx.conf", "match_line": "http {", "lines_to_insert": [" server_tokens off;", " client_max_body_size 20M;"] } ``` Example 2: Add a new host entry after localhost ```json { "file_path": "/etc/hosts", "match_line": "127.0.0.1 localhost", "lines_to_insert": ["192.168.1.10 myserver.local"] } ```

Move or rename a file or directory (works for both - whichever `source` is). If `destination` already exists: fails cleanly with `overwrite=False` (default); with `overwrite=True`, it's replaced (`mv -f`/`Move-Item -Force`). If `source` doesn't exist, also fails cleanly rather than raising. Returns: `{'success': True, 'message': str}` on success, or `{'success': False, 'message': str}` on failure (source not found, destination exists and `overwrite=False`, permission error) - not a raised exception.

Read file contents directly via SFTP. This tool reads raw bytes from the remote file using SFTP and decodes them on the client side. Unlike command-based file reading (cat, Get-Content), SFTP completely bypasses shell and console encoding issues. **Why use this instead of ssh_cmd_run with cat/Get-Content?** - Works correctly with Unicode on ALL platforms including Windows - Bypasses Windows PowerShell's OEM code page encoding problem - More efficient for binary-safe file transfer - No shell escaping issues with special characters in content Returns: Dictionary with: - success: True if file was read successfully - content: The file contents as a string - size: Number of bytes read - encoding: The encoding used to decode the content

Replace a line in a file with a new line. `match_line` must match EXACTLY ONE line in the file (whitespace-trimmed, literal text - not a pattern); if it matches zero lines or more than one, the operation fails with a descriptive error rather than guessing which line you meant. Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique. PARAMETERS: * file_path: Path to the file to modify * match_line: Exact line content to match and replace (whitespace-trimmed) * new_line: New line to insert in place of the match * use_sudo: Use sudo for the operation (default: false) * force: Force operation even if file can't be read (sudo only) (default: false) RETURNS: On success: `{'success': True, 'lines_written': 1}` (or, in the rare edge case where `new_line` is identical to the matched line, `{'success': True, 'message': 'No changes needed...'}` instead - nothing to write). On failure (match not found, match not unique, file not found/unreadable): `{'success': False, 'error': str}` - not a raised exception. Note: unlike some other file tools, this does NOT return `file_path` in the response. EXAMPLES: Example 1: Replace a commented line with an active configuration ```json { "file_path": "/etc/ssh/sshd_config", "match_line": "#ClientAliveInterval 0", "new_line": "ClientAliveInterval 300" } ``` Note: To delete a line entirely, use the dedicated ssh_file_delete_line_by_content tool instead. To replace/insert MULTIPLE lines in one call, use ssh_file_replace_line_multi instead.

Replace a line in a file with one or more new lines (or delete it, with an empty list). Use this instead of ssh_file_replace_line when you need to insert more than one line, or delete a line without using the separate ssh_file_delete_line_by_content tool. `match_line` must match EXACTLY ONE line in the file (whitespace-trimmed, literal text - not a pattern); if it matches zero lines or more than one, the operation fails with a descriptive error rather than guessing. Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique. PARAMETERS: * file_path: Path to the file to modify * match_line: Exact line content to match and replace (whitespace-trimmed) * new_lines: List of new lines to insert in place of the match - To replace with multiple lines: use ["first line", "second line", ...] - To delete the line entirely: use [] (empty list) - To replace with an empty line: use [""] * use_sudo: Use sudo for the operation (default: false) * force: Force operation even if file can't be read (sudo only) (default: false) RETURNS: On success: `{'success': True, 'lines_written': <len(new_lines)>}` (or, in the rare edge case where the result is byte-identical to the original file, `{'success': True, 'message': 'No changes needed...'}` instead). On failure (match not found, match not unique, file not found/unreadable): `{'success': False, 'error': str}` - not a raised exception. Note: does NOT return `file_path` in the response. EXAMPLES: Example 1: Replace a line with multiple lines ```json { "file_path": "/etc/hosts", "match_line": "127.0.0.1 localhost", "new_lines": ["127.0.0.1 localhost", "127.0.0.1 myhost.local"] } ``` Example 2: Delete a line entirely ```json { "file_path": "/etc/nginx/nginx.conf", "match_line": "# server_tokens off;", "new_lines": [] } ``` Example 3: Replace with an empty line ```json { "file_path": "/etc/ssh/sshd_config", "match_line": "PermitRootLogin yes", "new_lines": [""] } ```

Get status information about a file or directory (via SFTP stat - works the same way on all platforms, no shell command involved). On Windows, `mode`/`uid`/`gid` come from the SFTP subsystem's own cross-platform attribute reporting, not real Windows ACLs/ownership - Windows has no equivalent concept, so these values (e.g. `uid`/`gid` of `0`) are not meaningful there and should not be relied on to reason about actual Windows permissions/ownership. `type`/`size`/`atime`/`mtime` are unaffected and accurate on all platforms. Returns: `{'exists': True, 'path', 'type' ('file'/'directory'/'symlink'/'unknown'), 'mode' (octal string, e.g. "0o40755"), 'uid', 'gid', 'size' (bytes), 'atime', 'mtime'}` when the path exists. `atime`/`mtime` are raw numeric Unix timestamps (seconds since epoch, as returned by SFTP), not formatted date strings - convert with `datetime.fromtimestamp()` if you need a readable date. If the path does NOT exist (or stat failed for another reason, e.g. permission denied), returns `{'exists': False, 'path', 'error'}` instead - this is a normal, non-exceptional return value, not a raised error.

Transfer a single FILE between the local machine (running this MCP server) and the remote host, via SFTP. Both `local_path` and `remote_path` must be file paths, not directories - for whole-directory transfers, use ssh_dir_transfer instead. For remote-to-remote copies (no local machine involved), use ssh_file_copy instead. Caveat: `use_sudo=True` on download/upload stages a copy through `/tmp/` using Unix shell commands (`mv`/`chmod`/`rm`) - this only works against Linux/macOS remote hosts. Windows has no per-command sudo concept anyway (see ssh_conn_verify_sudo), so `use_sudo=True` against a Windows connection raises immediately instead of attempting these Unix commands - connect as Administrator instead. Returns: `{'operation' (human-readable description of what happened), 'success': True, 'local_path', 'remote_path', 'sudo', 'connection'}`. Raises an exception on failure rather than returning a `success: False` dict.

Create a new file, or overwrite/append to an existing one, with the given content (works the same whether or not the file already exists - `append=True` on a nonexistent file just creates it). Handles special characters and multi-line content properly. `mode` (Unix permission bits) is applied via a `chmod` command after writing - this only works on Linux/macOS. On Windows there's no equivalent, so `mode` is silently ignored there (same convention as `ssh_dir_mkdir`'s `mode` parameter). Returns: On success: `{'success': True, 'file_path', 'bytes_written' (int), 'mode' (octal string, or `None` if not set OR if the connection is Windows - the response never echoes back a mode value that wasn't actually applied), 'append' (bool, echoes the parameter), 'connection'}`. On failure (e.g. parent directory missing and `create_dirs=False`, write error): `{'success': False, 'file_path', 'error'}` - not a raised exception.

Disconnect the current SSH connection if one exists. Use this when you want to explicitly close the current SSH connection before connecting to a different host or when you're done with SSH operations. Returns: Dictionary with disconnection status

List all configured SSH hosts with their aliases and descriptions. This is the ONLY correct way to see what hosts are configured - never read the host configuration TOML file directly (ssh_conn_add_host's docstring names its path). That file stores every host's password, sudo password, and key passphrase in plaintext; this tool deliberately omits all of that and returns only the fields below. If you need to add, change, or remove a host, use ssh_conn_add_host, ssh_host_update, or ssh_host_remove instead of editing the file - between those and ssh_host_use_config, there is no legitimate reason to open it. Lists hosts from whichever config file is currently active - the server's default unless ssh_host_use_config was called to switch to an alternate file. The returned `config_path` always shows which one that is. Returns: Dictionary with: - hosts: List of host information dictionaries, each containing: - key: The 'user@host' key - alias: Optional short name for the host - description: Optional description of the host - config_path: The host configuration file this list came from

Remove a host configuration from the host configuration TOML file (see ssh_conn_add_host's docstring for its exact path and why you should never read it directly - use ssh_host_list to see what's configured instead). To change a host's password/port/etc. rather than deleting it, use ssh_host_update instead - removing and re-adding loses every field you don't explicitly resupply. Returns: Dictionary with operation status

Update one or more fields of an existing host configuration - this is the safe way to rotate a password, change a port, or adjust other settings without ever needing to read or hand-edit the host configuration TOML file (which stores every host's credentials in plaintext - never read it directly; this tool, ssh_conn_add_host, ssh_host_remove, and ssh_host_list cover everything you should need). Only the fields you pass are changed - any parameter left at its default (omitted/`None`) keeps its current value. To clear a field entirely (e.g. drop a password when switching a host to key-only auth), pass an empty string `""` rather than omitting it. `user`/`host` themselves can't be changed this way (that changes the 'user@host' key identity) - remove and re-add instead if you need that. Prefer this over ssh_host_remove + ssh_conn_add_host for adjusting an existing host: remove+re-add loses every field you don't explicitly resupply, since ssh_conn_add_host has no knowledge of the entry it just deleted. `host_name` may be either the 'user@hostname' key or a configured alias - resolved the same way as ssh_conn_connect. Warn the user that any new password/passphrase value passed here will be visible to the LLM, the same caveat as ssh_conn_add_host. Returns: On success: `{'status': 'success', 'message', 'key', 'updated_fields' (list of field names that were actually changed)}`. On failure (the update would leave neither a password nor a keyfile set, or a duplicate alias): `{'status': 'error', 'error': <message>}` - not a raised exception. Raises: SshError: If `host_name` doesn't resolve to any configured host (tried as both key and alias).

Switch which host configuration file ssh_host_list, ssh_conn_connect, ssh_conn_add_host, ssh_host_update, and ssh_host_remove all operate against, for the rest of this session (or until you call this again) - not just for one call. This is the same "one active thing at a time" model ssh_conn_connect uses for SSH connections, applied to host configuration files instead; the two are completely independent (switching config files doesn't affect any current SSH connection, and vice versa). Use this when you want to browse or use hosts from a different TOML file than the server's default - e.g. a separate list of hosts for a different environment/project. The alternate file must already exist and be a valid host configuration TOML file (see ssh_conn_add_host's docstring for the format) - this deliberately does NOT auto-create a missing file the way the server's own default config file is created on first run, since an LLM-supplied path with a typo should fail loudly rather than silently create a stray file somewhere. Omit `config_path` (or pass `""`) to switch back to the server's original default configuration file. ssh_host_list's response always includes `config_path` showing whichever file is currently active, so you can check before mutating anything with ssh_conn_add_host/ssh_host_update/ssh_host_remove. Returns: On success: `{'status': 'success', 'message', 'config_path', 'is_default' (bool), 'host_count'}`. On failure (path doesn't exist, path is a directory, or the file fails to parse as valid host config TOML): `{'status': 'error', 'error': <message>}` - not a raised exception.

Terminate a background task (launched via ssh_task_launch, or any other real remote PID) by sending a signal to its PID. If force=True and the process doesn't exit after wait_seconds, it will be forcibly killed with SIGKILL (signal 9). With `use_sudo=True` on a 'linux'/'flex' connection with a BusyBox-style `ps` that doesn't support `-o pgid=` (check `ssh_conn_connect`/ `ssh_conn_host_info`'s `capabilities`), this raises a clear error instead of running - there is no clean fallback, since killing just the captured PID (rather than its whole process group) can leave the sudo'd command's real child process(es) running as orphans, exactly the failure mode this check exists to prevent. Not an issue with `use_sudo=False`. Returns: `{'pid', 'result', 'signal', 'force_kill_used', 'timestamp'}`. `result` is one of: - 'killed': confirmed terminated (by the initial signal or the force-kill fallback - see `force_kill_used` to tell which). Terminal - nothing left to check. - 'already_exited': the process was already gone before any signal was sent. Terminal. - 'failed_to_kill': still running after both the signal and force-kill attempt (or after the signal alone, if `force=False`). Not terminal - the process is still alive; consider retrying or investigating why it won't die. - 'invalid_pid': `pid` wasn't a valid positive integer - no signal was sent. - 'error': the kill attempt itself failed unexpectedly (e.g. connection issue) - the process's actual state is unknown, not necessarily still running. `force_kill_used` is True iff the SIGKILL fallback was actually attempted (the initial signal alone was not enough to end the process), regardless of whether the fallback itself succeeded - False if the initial signal alone was sufficient, the process was already gone, `pid` was invalid, or `force=False` so no fallback was ever attempted.

Launch a command in the background and return its PID immediately, without waiting for it to complete. Prefer this over ssh_cmd_run for commands that will take a long time or may be quiet for extended periods: package installs, container/image pulls, large downloads, backups, compilation. It avoids holding a blocking tool call open and the ambiguity of io_timeout - the PID it returns survives reconnects and can be checked anytime with ssh_task_status(pid), and stdout_log/stderr_log can be read with ssh_file_read while the task is still running. Output is redirected to files (see stdout_log/stderr_log), not captured in memory - read the log files to see progress or final output. Returns: `{'command', 'pid', 'start_time', 'stdout_log', 'stderr_log'}`. `stdout_log`/ `stderr_log` are `None` if `log_output=False`. If you didn't pass an explicit `stdout_log`/`stderr_log` yourself, the returned path reflects the actual default log location used - `/tmp/task-<pid>.log` on Linux/macOS, `C:\Windows\Temp\task-<pid>.log` on Windows.

Check the liveness of a background task by PID (from ssh_task_launch, or any other real remote PID - e.g. the `pid` field from ssh_cmd_run). This does a live check on the remote host every call, not a cached lookup, so it's safe to call repeatedly. Returns: `{'pid', 'status', 'running' (bool, True iff status=='running'), 'timestamp'}`. `status` is one of: - 'running': the process currently exists. - 'exited': the process is gone - it either completed or was killed; there's no way to distinguish which, or recover its exit code, from this tool alone. - 'invalid': the given `pid` isn't a valid positive integer. - 'error': the liveness check itself failed (e.g. connection issue) - this does NOT mean the process exited, just that its status is unknown.