MCP SSH Session

You are using an MCP server that enables AI agents to establish and manage persistent SSH sessions. This design keeps connections alive across commands, supports multiple hosts, and handles privileged operations safely, allowing you to automate remote administration tasks with persistence and observability.

How to use

You can operate SSH sessions through a client that communicates with the MCP server. Start a persistent session to a target host, then execute multiple commands over that session without reconnecting each time. Use the async execution flow to run long-running tasks without blocking the server, and leverage features like sudo handling, SFTP file access, and enable-mode support for network devices. You can manage multiple sessions, read remote files, write to them, and interrupt or query the status of in-flight commands.

Key usage patterns include: starts a persistent shell, runs a sequence of commands, and optionally feeds input to interactive prompts. When connecting to network devices, you can enable privileged modes, and when accessing Unix-like systems, you can perform sudo-aware actions. If a command runs longer than expected, you can request a status update or interrupt it by its command ID. You can also read and write files remotely via SFTP, with built-in fallbacks for sudo-required files.

How to install

Prerequisites: you need Node.js and npm, or Python in a development setup, depending on how you install and run the MCP server in your environment.

Install and run the MCP server via the local package runner shown in the available setup options.

Concrete steps from the source are to install the CLI tool and register the MCP server with a client, then verify the server is reachable. Follow the exact run sequence described in the provided install snippets to ensure the correct runtime environment.

Configuration and usage notes

The server supports reading your SSH config at ~/.ssh/config to reuse host definitions, ports, usernames, and identity files. It also provides an environment-override mechanism for credential hiding, so agents can operate using aliases while real credentials stay protected in the server configuration.

From the usage perspective you can configure a session at runtime by selecting the target host, providing credentials if needed, and choosing the command to run. For network devices, specify enable passwords when required. For Linux hosts, provide sudo passwords when necessary.

The server offers several commands to manage sessions and commands, including launching new persistent sessions, listing active sessions, closing sessions, and performing asynchronous command execution with status tracking.

Security and observability notes

Credential handling includes an optional sudo password field and optional sudo usage to accommodate protected operations. SFTP access for file transfers is preferred when possible, with a shell-based sudo tee fallback for write operations that require elevated permissions. The design emphasizes persistence and non-blocking behavior to maintain responsiveness and safe, observable command execution.

You can interrupt running commands by id, query command history, and review outputs through status endpoints. Network device operations, file transfers, and command execution are all designed to be thread-safe and concurrent-ready.

Troubleshooting and tips

If a session appears to hang, check for an idle timeout transition path and ensure the command is not blocked by a long-running process. If a host becomes unreachable, the server can automatically attempt to reconnect and resume operations when the connection is restored.

Ensure your SSH config is correctly formatted and accessible by the MCP server. If you rely on aliasing or host-name mappings, verify those definitions are loaded properly. For sensitive environments, use environment-variable overrides to prevent credentials from leaking into AI contexts.

Available tools

execute_command

Execute a command on an SSH host using a persistent session with smart timeout handling, optional interactive prompts, and session persistence.

list_sessions

List all active SSH sessions.

close_session

Close a specific SSH session by host or session identifier.

close_all_sessions

Close all active SSH sessions.

execute_command_async

Execute a command asynchronously, returning a command ID for tracking without blocking the server.

get_command_status

Retrieve the status and output for an asynchronous command using its command ID.

interrupt_command_by_id

Interrupt a running asynchronous command by sending an interrupt signal.

list_running_commands

List all currently running asynchronous commands.

list_command_history

List recent command history, including completed, failed, or interrupted commands.

read_file

Read a remote file via SFTP with optional sudo support, preferring SFTP and falling back to sudo cat when needed.

write_file

Write content to a remote file via SFTP with optional sudo support, and with options to append, create directories, and set permissions.