MCP SSH Session

[!IMPORTANT] Alternative version: mcp-ssh-tmux. Uses tmux for improved persistence, observability, and a superior “LLM-as-Observer” approach.

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

uvx mcp-ssh-session

Using Claude Code

Add to your ~/.claude.json:

{
  "mcpServers": {
    "ssh-session": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-ssh-session"],
      "env": {}
    }
  }
}

Using MCP Inspector

npx @modelcontextprotocol/inspector uvx mcp-ssh-session

Development Installation

uv venv
source .venv/bin/activate
uv pip install -e .

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:

{
  "host": "myserver",
  "command": "uptime"
}

Using explicit parameters:

{
  "host": "example.com",
  "username": "user",
  "command": "ls -la",
  "key_filename": "~/.ssh/id_rsa",
  "port": 22
}

Network device with enable mode:

{
  "host": "router.example.com",
  "username": "admin",
  "password": "ssh_password",
  "enable_password": "enable_password",
  "command": "show running-config"
}

Unix/Linux with sudo:

{