Establish an SSH connection to a remote server.

This tool creates a new SSH session that can be used for subsequent operations like command execution, file upload/download, and directory listing.

Args: params (ConnectInput): Validated input parameters containing: - host (str): Remote server hostname or IP address (e.g., "192.168.1.100", "server.example.com") - port (int): SSH port number, default 22, range 1-65535 - username (str): SSH username for authentication - password (Optional[str]): Password for authentication (alternative to private_key_path) - private_key_path (Optional[str]): Path to SSH private key file (alternative to password) - private_key_password (Optional[str]): Password for encrypted private key - timeout (int): Connection timeout in seconds, default 30, range 1-300 - session_id (Optional[str]): Session identifier, auto-generated if omitted

Returns: str: Session ID for the established connection or error message

Examples: - Use when: "Connect to server 192.168.1.100 with username admin" -> params with host="192.168.1.100", username="admin" - Use when: "Connect using SSH key" -> params with private_key_path="/path/to/key" - Don't use when: Session already exists (use ssh_status to check) - Don't use when: Need to execute multiple commands to different servers (create separate sessions)

Error Handling: - Returns error if authentication fails (check credentials) - Returns error if host is unreachable (check network) - Returns error if port is invalid or service not running

Check the status of SSH connection sessions.

This tool reports which SSH sessions are active and their connection details.

Args: params (StatusInput): Validated input parameters containing: - session_id (Optional[str]): Specific session to check, or None to list all active sessions

Returns: str: JSON-formatted status information for active sessions

Examples: - Use when: "Check all active SSH connections" -> params with session_id=None - Use when: "Verify if connection to server is still active" -> params with specific session_id - Don't use when: Need to execute commands (use ssh_execute instead)

Error Handling: - Returns "No active sessions" if no connections are established - Returns specific session info if session_id is provided and valid

Execute a command on the remote server via SSH.

This tool runs a shell command on the connected server and captures stdout, stderr, and exit code. The command runs in a non-interactive shell.

Args: params (ExecuteInput): Validated input parameters containing: - session_id (str): SSH session identifier from ssh_connect - command (str): Command to execute on remote server (e.g., "ls -la", "whoami", "cat /etc/os-release") - working_directory (Optional[str]): Working directory for command execution (e.g., "/var/log") - timeout (int): Execution timeout in seconds, default 30, range 1-600 - response_format (ResponseFormat): Output format (markdown or json)

Returns: str: Command execution result with stdout, stderr, and exit code

Examples: - Use when: "Check what Linux distribution is running" -> params with command="cat /etc/os-release" - Use when: "List files in /var/log" -> params with command="ls -la /var/log" - Use when: "Check disk usage" -> params with command="df -h" - Don't use when: Need interactive commands (e.g., vim, top - use non-interactive alternatives) - Don't use when: Need to run multiple commands in sequence (execute tools separately)

Error Handling: - Returns "Error: Session not found" if session_id is invalid - Returns execution result with non-zero exit code if command fails - Returns timeout error if command exceeds timeout limit

Upload a local file to the remote server via SFTP.

This tool transfers a file from the local machine to the connected SSH server.

Args: params (UploadFileInput): Validated input parameters containing: - session_id (str): SSH session identifier from ssh_connect - local_path (str): Path to local file to upload (e.g., "./config.json", "/tmp/data.csv") - remote_path (str): Destination path on remote server (e.g., "/tmp/config.json", "~/mydata.csv") - file_mode (int): File permissions in octal, default 0o644 (rw-r--r--)

Returns: str: Upload confirmation with file size and paths

Examples: - Use when: "Upload config.json to /tmp/" -> params with local_path="./config.json", remote_path="/tmp/config.json" - Use when: "Transfer script to home directory" -> params with local_path="script.sh", remote_path="~/script.sh" - Don't use when: Remote file already exists (use ssh_execute with rm first or set file_mode accordingly) - Don't use when: Need to upload multiple files (call this tool multiple times)

Error Handling: - Returns "Error: Session not found" if session_id is invalid - Returns error if local file doesn't exist - Returns error if remote directory doesn't have write permissions - Returns error if file size is too large for available bandwidth

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

This tool transfers a file from the connected SSH server to the local machine.

Args: params (DownloadFileInput): Validated input parameters containing: - session_id (str): SSH session identifier from ssh_connect - remote_path (str): Path to remote file to download (e.g., "/var/log/syslog") - local_path (str): Destination path for downloaded file (e.g., "./syslog", "/tmp/downloaded.log") - overwrite (bool): Overwrite local file if it exists, default False

Returns: str: Download confirmation with file size and paths

Examples: - Use when: "Download /var/log/syslog to local machine" -> params with remote_path="/var/log/syslog", local_path="./syslog" - Use when: "Get config file from server" -> params with remote_path="/etc/app/config", local_path="config" - Don't use when: Local file exists and overwrite=False - Don't use when: Need to download multiple files (call this tool multiple times)

Error Handling: - Returns "Error: Session not found" if session_id is invalid - Returns error if remote file doesn't exist - Returns error if local file exists and overwrite=False - Returns error if local directory doesn't have write permissions

List files and directories in a remote directory via SFTP.

This tool provides a directory listing with file metadata including size, type, and modification time.

Args: params (ListFilesInput): Validated input parameters containing: - session_id (str): SSH session identifier from ssh_connect - remote_path (str): Path to remote directory to list (e.g., "/var/log", "~", "/tmp") - show_hidden (bool): Show hidden files (starting with .), default False - response_format (ResponseFormat): Output format (markdown or json)

Returns: str: Directory listing with file details

Examples: - Use when: "List files in /var/log" -> params with remote_path="/var/log" - Use when: "Show all files including hidden ones in home directory" -> params with remote_path="~", show_hidden=True - Use when: "Check what's in /tmp" -> params with remote_path="/tmp" - Don't use when: Need to list files on local machine (use local filesystem instead)

Error Handling: - Returns "Error: Session not found" if session_id is invalid - Returns error if remote directory doesn't exist - Returns error if directory is not readable due to permissions

Close an SSH connection session.

This tool terminates an SSH session and frees associated resources.

Args: params (DisconnectInput): Validated input parameters containing: - session_id (str): SSH session identifier to close

Returns: str: Disconnection confirmation

Examples: - Use when: "Close SSH connection to server" -> params with session_id="admin@192.168.1.100:22" - Use when: "Done working with server, disconnect" -> params with session_id (from ssh_connect) - Don't use when: Session doesn't exist (ssh_status will show this) - Don't use when: Need to continue working with the server

Error Handling: - Returns "Error: Session not found" if session_id is invalid - Returns success even if session was already closed