MCP SSH Session

An MCP (Model Context Protocol) server that enables AI agents to establish and manage persistent SSH sessions.

Features

• Smart Command Execution: Never hangs the server - automatically transitions to async mode if timeout is reached

• Persistent Sessions: SSH connections are reused across multiple command executions

• Async Command Execution: Non-blocking execution for long-running commands

• SSH Config Support: Automatically reads and uses settings from ~/.ssh/config

• Multi-host Support: Manage connections to multiple hosts simultaneously

• Automatic Reconnection: Dead connections are detected and automatically re-established

• Thread-safe: Safe for concurrent operations

• Network Device Support: Automatic enable mode handling for routers and switches

• Sudo Support: Automatic password handling for sudo commands on Unix/Linux hosts

• File Operations: Safe helpers to read and write remote files over SFTP

• Command Interruption: Send Ctrl+C to interrupt running commands

Installation

Using uvx

Using Claude Code

Add to your ~/.claude.json:

Using MCP Inspector

Development Installation

Usage

Available Tools

execute_command

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

Smart Execution: Starts synchronously and waits for completion. If timeout is reached, automatically transitions to async mode and returns a command ID. Server never hangs!

Advanced Features:

• Automatic timeout handling with async transition

• Interactive command support (use send_input for prompts)

• Command interruption capability (interrupt_command_by_id)

• Session persistence across multiple commands

Using SSH config alias:

Using explicit parameters:

Network device with enable mode:

Unix/Linux with sudo:

list_sessions

List all active SSH sessions.

close_session

Close a specific SSH session.

close_all_sessions

Close all active SSH sessions.

execute_command_async

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

Use with companion tools:

• get_command_status(command_id) - Check progress and retrieve output

• interrupt_command_by_id(command_id) - Send Ctrl+C to stop execution

• send_input(command_id, text) - Provide input to interactive commands

get_command_status

Get the status and output of an async command.

interrupt_command_by_id

Interrupt a running async command by sending Ctrl+C.

list_running_commands

List all currently running async commands.

list_command_history

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

read_file

Read the contents of a remote file via SFTP, with optional sudo support.

Basic usage:

With passwordless sudo (NOPASSWD in sudoers):

With sudo password:

• Attempts SFTP first for best performance

• Falls back to sudo cat via shell if permission denied and use_sudo=true or sudo_password provided

• Supports both passwordless sudo (NOPASSWD) and password-based sudo

• Enforces a 2 MB maximum per request (configurable per call up to that limit)

• Returns truncated notice when the content size exceeds the requested limit

write_file

Write text content to a remote file via SFTP, with optional sudo support.

Basic usage:

With passwordless sudo (NOPASSWD in sudoers):

With sudo password:

• Uses SFTP when use_sudo=false and no sudo_password provided

• Uses sudo tee via shell when use_sudo=true or sudo_password is provided

• Supports both passwordless sudo (NOPASSWD) and password-based sudo

• Content larger than 2 MB is rejected for safety

• Optional append mode to add to existing files

• Optional make_dirs flag will create missing parent directories

• Supports permissions to set octal file modes after write (e.g., 420 for 0644)

• Note: Shell fallback is slower than SFTP but enables writing to protected files

SSH Config Support

The server automatically reads ~/.ssh/config and supports:

• Host aliases

• Hostname mappings

• Port configurations

• User specifications

• IdentityFile settings

Example ~/.ssh/config:

Then simply use:

How It Works

Persistent Shell Sessions

Commands execute in persistent interactive shells that maintain state:

• Current directory persists across commands (cd /tmp stays in /tmp)

• Environment variables remain set

• Shell history is maintained

Smart Command Completion Detection

Commands complete when either:

1. Prompt detected: Standard shell prompts ($, #, >, %) at end of output

2. Idle timeout: No output for 2 seconds after receiving data

Why idle timeout? Custom themed prompts may not match standard patterns. The 2-second idle timeout ensures commands complete even with non-standard prompts.

Long-running commands: The idle timer resets every time new output arrives, so builds or scripts that output sporadically continue running until naturally complete or the overall timeout is reached.

Documentation

• ASYNC_COMMANDS.md - Smart execution and async commands

• SAFETY_PROTECTIONS.md

License

Distributed under the MIT License. See LICENSE for details.