Execute a command on an SSH host using a persistent session.

Starts synchronously and waits for completion. If the command doesn't complete within the timeout, it automatically transitions to async mode and returns a command ID for tracking.

The host parameter can be either a hostname/IP or an SSH config alias. If an SSH config alias is provided, configuration will be read from ~/.ssh/config.

For network devices (routers, switches), use enable_password to automatically enter privileged/enable mode before executing commands.

For Unix/Linux hosts requiring sudo, use sudo_password to automatically handle the sudo password prompt. The command will be automatically prefixed with 'sudo' if not already present.

Advanced Features:

• Automatic timeout handling with async transition

• Interactive command support with input capability

• Command interruption (Ctrl+C) for stuck processes

• Session persistence across multiple commands

Args: host: Hostname, IP address, or SSH config alias (e.g., "myserver") command: Command to execute username: SSH username (optional, will use SSH config or current user) password: Password (optional) key_filename: Path to SSH key file (optional, will use SSH config) port: SSH port (optional, will use SSH config or default 22) enable_password: Enable mode password for network devices (optional) enable_command: Command to enter enable mode (default: "enable") sudo_password: Password for sudo commands on Unix/Linux hosts (optional) timeout: Timeout in seconds for command execution (default: 30)

List all active SSH sessions.

Close a specific SSH session.

The host parameter can be either a hostname/IP or an SSH config alias.

Args: host: Hostname, IP address, or SSH config alias username: SSH username (optional, will use SSH config or current user) port: SSH port (optional, will use SSH config or default 22)

Close all active SSH sessions.

Read a remote file over SSH.

Attempts to read using SFTP first. If permission is denied and use_sudo is True or sudo_password is provided, falls back to using 'sudo cat' via shell command.

Args: host: Hostname, IP address, or SSH config alias remote_path: Path to the remote file username: SSH username (optional) password: SSH password (optional) key_filename: Path to SSH key file (optional) port: SSH port (optional) encoding: Text encoding (default: utf-8) errors: Error handling for decoding (default: replace) max_bytes: Maximum bytes to read (default: 2MB) sudo_password: Password for sudo (optional, not needed if NOPASSWD configured) use_sudo: Use sudo for reading (tries passwordless if no sudo_password provided)

Write content to a remote file over SSH.

If use_sudo is True or sudo_password is provided, uses sudo via shell commands (tee). Otherwise, attempts to write using SFTP.

Args: host: Hostname, IP address, or SSH config alias remote_path: Path to the remote file content: Content to write username: SSH username (optional) password: SSH password (optional) key_filename: Path to SSH key file (optional) port: SSH port (optional) encoding: Text encoding (default: utf-8) errors: Error handling for encoding (default: strict) append: Append to file instead of overwriting (default: False) make_dirs: Create parent directories if they don't exist (default: False) permissions: Octal file permissions to set (e.g., 420 for 0644) max_bytes: Maximum bytes to write (default: 2MB) sudo_password: Password for sudo (optional, not needed if NOPASSWD configured) use_sudo: Use sudo for writing (tries passwordless if no sudo_password provided)

Execute a command asynchronously without blocking the server.

Returns a command ID that can be used to check status, retrieve output, or interrupt. Useful for long-running commands like 'sleep 60', monitoring tasks, or large operations.

Use with companion tools:

• get_command_status(command_id) to check progress and retrieve output

• interrupt_command_by_id(command_id) to send Ctrl+C and stop execution

• send_input(command_id, text) to provide input to interactive commands

Args: host: Hostname, IP address, or SSH config alias command: Command to execute username: SSH username (optional) password: SSH password (optional) key_filename: Path to SSH key file (optional) port: SSH port (optional) timeout: Maximum execution time in seconds (default: 300)

Get the status and output of an async command.

Args: command_id: The command ID returned by execute_command_async

Interrupt a running async command by sending Ctrl+C.

Args: command_id: The command ID returned by execute_command_async

List all currently running async commands.

List recent command history (completed, failed, interrupted commands).

Args: limit: Maximum number of commands to return (default: 50)

Send input to a running async command and return any new output.

Useful for interacting with commands that require user input, such as:
- Pagers (less, more): send 'q' to quit, space to page down
- Yes/no prompts: send 'y' or 'n'
- Interactive programs: send appropriate responses

Args:
    command_id: The command ID to send input to
    input_text: Text to send (e.g., 'q', 'y

', etc.)

Send input to the active shell for a session.

Useful for clearing stuck interactive states or sending input to the current shell.

Args:
    host: Hostname, IP address, or SSH config alias
    input_text: Text to send (e.g., 'q

' to quit pager, '' for Ctrl+C) username: SSH username (optional) port: SSH port (optional)

Read the terminal screen state for a session.

Returns the current screen content from the terminal emulator, including cursor position. Only works when MCP_SSH_INTERACTIVE_MODE=1 is set.

Args: host: Hostname, IP address, or SSH config alias username: SSH username (optional, will use SSH config or current user) port: SSH port (optional, will use SSH config or default 22) max_lines: Maximum number of lines to return (default: 24)

Returns: JSON string with screen lines, cursor position, and dimensions

Send special keys or key sequences to a session.

Supports special key tokens:

• or : Send newline

• or : Send escape key

• : Send tab key

• : Send Ctrl+C (interrupt)

• : Send Ctrl+D (EOF)

• : Send Ctrl+Z (suspend)

• , , , : Arrow keys

• : Space character

Regular text is sent as-is. Mix special keys with text: "helloworld"

Args: host: Hostname, IP address, or SSH config alias keys: Key sequence to send (e.g., "q", ":wq", "") username: SSH username (optional) port: SSH port (optional)

Returns: Success message