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.

Check if there is an active SSH connection.

Returns: bool: True if an active connection exists, False otherwise.

Establish an SSH connection using a pre-configured host. The host can be specified by its 'user@hostname' key or by its alias.

Returns: Dictionary with connection status and detailed system information

Add or update a host configuration in the host configuration TOML file. This tool will fail if the host already exists in the host config file.

You can call the 'ssh_conn_connect' tool without having to add a new host! The host may already be listed in the host config TOML file!

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.

The host config file is a TOML file likely in the user's home directory. The configuration will be stored under a ["user@host"] key.

Optional fields:

• alias: A short name for connecting (e.g., 'prod' instead of 'deploy@production.example.com')

• description: A text description of what the host is for

Returns: Dictionary with operation status

Get essential SSH connection status information.

Returns: Dictionary containing basic connection status (user, working directory, OS type)

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.

List all configured SSH hosts with their aliases and descriptions.

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

Remove a host configuration from the host configuration TOML file.

Returns: Dictionary with operation status

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

Verify if sudo access is available on the remote system.

On Linux/macOS: Checks if sudo is available and whether it requires a password. The use_sudo parameter will run commands with sudo, prompting for password if needed.

On Windows: Checks if the session is running as Administrator. Windows cannot elevate privileges on-demand like sudo. If you need elevated access on Windows, you must connect with an Administrator account from the start.

Returns: Dictionary with sudo access information: - available: True if any sudo access is available - passwordless: True if passwordless sudo is available (or elevated on Windows) - requires_password: True if sudo requires a password

Check the status of a background task by PID.

Returns: Dictionary containing task status information

Terminate a background task 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).

Returns: Dictionary containing kill operation result

Execute a command on the remote host and return the results. Handles both immediate and long-running operations. Manages timeouts (I/O timeout and runtime timeout). Work with runtime_timeout primarily which should be set to something reasonable. If timeout occurs, you can use 'ssh_cmd_check' tool to check on the running command. Note that 'ssh_cmd_check' can be called immediately with a 'wait_seconds' argument where it waits for a given number of seconds and then returns with the command status. This way you can poll the command status until it completes. The command can also be killed using 'ssh_cmd_kill' tool. You can access the command history using the 'ssh_cmd_history' tool to see what were previous commands and what output they produced.

Returns: Dictionary containing command output, status, and metadata. Status field indicates success or the type of failure (timeout, runtime_timeout, etc.)

Terminate a currently running command by its handle ID.

This tool is specifically for killing commands started with ssh_cmd_run, not background tasks launched with ssh_task_launch.

If force=True and the process doesn't exit after wait_seconds, it will be forcibly killed with SIGKILL (signal 9).

Returns: Dictionary containing kill operation result

Wait for the specified duration and then check the status of a command.

This tool helps with monitoring long-running commands started with ssh_cmd_run by implementing a wait operation that LLMs cannot perform on their own.

Returns: Dictionary containing command status information after waiting

Retrieve output from a specific command execution.

Returns: List of output lines from the command

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 - output: Command output snippet (if include_output=True)

Launch a command in the background and return its PID.

Unlike ssh_run, this does not wait for the command to complete. Output is redirected to files or /dev/null, not captured in memory.

Returns: Dictionary containing task information including PID

Create a directory on the remote system.

Returns: Dictionary with operation status

Remove a directory on the remote system.

Returns: Dictionary with operation status

List contents of a directory on the remote system.

Returns: List of filenames in the directory

Get status information about a file or directory.

Returns: Dictionary with file/directory metadata. Includes 'exists': True/False. If exists, includes 'type': ('file', 'directory', 'symlink', 'unknown'), 'mode' (octal string), 'uid', 'gid', 'size', 'atime', 'mtime'.

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

Search for a pattern in a remote file and return matching lines.

Returns: Dictionary with total matches and list of matches (line number and content)

Get lines before and after a line that matches exactly.

Returns: Dictionary with match line number and context block

Replace a unique line in a file with a new line.

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: A dictionary with operation status including:

• success: Boolean indicating if operation succeeded

• file_path: Path to the modified file

EXAMPLES: Example 1: Replace a commented line with an active configuration

{
  "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.

Replace a unique line in a file with multiple new lines.

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: A dictionary with operation status including:

• success: Boolean indicating if operation succeeded

• file_path: Path to the modified file

EXAMPLES: Example 1: Replace a line with multiple lines

{
  "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

{
  "file_path": "/etc/nginx/nginx.conf",
  "match_line": "# server_tokens off;",
  "new_lines": []
}

Example 3: Replace with an empty line

{
  "file_path": "/etc/ssh/sshd_config",
  "match_line": "PermitRootLogin yes",
  "new_lines": [""]
}

Transfer files between local and remote systems.

Returns: Dictionary containing transfer status and metadata

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

Insert lines after a unique line match (ignoring leading/trailing whitespace).

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: A dictionary with operation status including:

• success: Boolean indicating if operation succeeded

• file_path: Path to the modified file

EXAMPLES: Example 1: Insert configuration lines after a marker

{
  "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

{
  "file_path": "/etc/hosts",
  "match_line": "127.0.0.1 localhost",
  "lines_to_insert": ["192.168.1.10 myserver.local"]
}

Delete a line matching a unique content string.

Returns: Dictionary with operation status

Copy a file with optional timestamp appended to the destination.

Returns: Dictionary with operation status

Create a new file or overwrite/append to an existing file with specified content. Handles special characters and multi-line content properly.

Returns: Dictionary with operation status and details

Move or rename a file or directory.

Returns: Dictionary with operation status

Recursively search for files matching a pattern.

Returns: List of dictionaries with file information

Calculate the total size of a directory recursively.

Returns: Dictionary with size information

Delete a directory and all its contents recursively.

Returns: Dictionary with deletion status and details

Delete all files matching a pattern under a directory.

Returns: Dictionary with deletion status and details

List contents of a directory recursively with detailed information.

Returns: List of dictionaries with file/directory information

Search for text patterns in files of given directory.

Returns: List of dictionaries with search matches

Copy a directory recursively.

Returns: Dictionary with copy operation details

Create a compressed archive from a directory.

Returns: Dictionary with archive information

Extract a tar or tar.gz archive to a directory.

Returns: Dictionary with extraction information