{"id":"b1cddcdc-69a3-445b-9d76-b99e28e43c2e","slug":"mcp-ssh-reloaded","kind":"mcp","name":"mcp-ssh-reloaded","summary":"MCP server for persistent SSH sessions but refactored version.","owner":"AmritaBot","repoUrl":"https://github.com/AmritaBot/mcp-ssh-reloaded","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-07-12T10:30:42.000Z","addedAt":"2026-10-21T04:49:01.825Z","logoUrl":"https://avatars.githubusercontent.com/u/229280225?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge"],"tags":["ssh-manager","ssh-session","model-context-protocol-server"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T01:34:30.805Z","sample":false,"url":"https://conduits.dev/tools/mcp-ssh-reloaded","language":"Python","transports":["stdio"],"install":{"pypi":"mcp-ssh-reloaded"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# MCP SSH Session - Reloaded\n\nAn MCP (Model Context Protocol) server that enables AI agents to establish and manage persistent SSH sessions.\n\n## Features\n\n- **Smart Command Execution** - auto-transitions to async mode if timeout is reached\n- **Persistent Sessions** - SSH connections reused across commands\n- **Async Commands** - non-blocking execution for long-running tasks\n- **SSH Config Support** - reads `~/.ssh/config` for aliases, ports, keys\n- **Multi-host** - manage connections to multiple hosts simultaneously\n- **Network Devices** - enable mode handling for Cisco, Juniper, MikroTik, etc.\n- **Sudo Support** - automatic password handling for Unix/Linux hosts\n- **File Operations** - read/write remote files via SFTP (sudo fallback)\n- **Command Interruption** - send Ctrl+C to stop running commands\n- **Thread-safe** - safe for concurrent operations\n- **Async Native** - built-in support for asynio.\n\n## Quick Start\n\n### 📦 Migrating from `mcp-ssh-session`\n\nThis project is a drop-in replacement for the original [`devnullvoid/mcp-ssh-session`](https://github.com/devnullvoid/mcp-ssh-session). To migrate:\n\n1. **Replace the package name** - `mcp-ssh-session` → `mcp-ssh-reloaded`\n2. **Environment variables fully inherited** - all `OVRD_*` and `MCP_SSH_*` env vars work the same\n3. **That's it** - reconnect and you're done\n\n\n\n\n
Before (old)After (new)
\n\n```json\n{\n \"mcpServers\": {\n \"ssh-session\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-ssh-session\", \"serve\", \"mcp\"]\n }\n }\n}\n```\n\n\n\n```json\n{\n \"mcpServers\": {\n \"ssh-session\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-ssh-reloaded\", \"serve\", \"mcp\"]\n }\n }\n}\n```\n\n
\n\n### Install\n\n```bash\nuvx mcp-ssh-reloaded\n```\n\n### Development\n\n```bash\nuv venv\nsource .venv/bin/activate\nuv pip install -e .\n```\n\n### CLI\n\n```bash\n# MCP server (default)\nmcp-ssh-reloaded serve mcp\n\n# Direct execution (no MCP)\nmcp-ssh-reloaded exec myserver \"uname -a\" -u admin\n\n# List / close sessions\nmcp-ssh-reloaded list\nmcp-ssh-reloaded close-all\n```\n\n### MCP Client Config\n\n**Claude Code / Desktop** (`~/.claude.json` or `claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"ssh-session\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"mcp-ssh-reloaded\", \"serve\", \"mcp\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Quick Examples\n\n```json\n// SSH config alias\n{ \"host\": \"myserver\", \"command\": \"uptime\" }\n\n// Explicit params\n{ \"host\": \"example.com\", \"username\": \"user\", \"command\": \"ls -la\", \"port\": 2222 }\n\n// Network device (Cisco enable mode)\n{ \"host\": \"router\", \"username\": \"admin\", \"enable_password\": \"secret\", \"command\": \"show run\" }\n\n// Unix with sudo\n{ \"host\": \"server\", \"username\": \"ops\", \"sudo_password\": \"secret\", \"command\": \"systemctl restart nginx\" }\n```\n\n---\n\n> **Full API reference:** [API-DOCS.md](./API-DOCS.md) - all types, all methods, all MCP tools, error handling, server config tunables.\n\n## SSH Config\n\n`~/.ssh/config` is read automatically:\n\n```\nHost myserver\n HostName example.com\n User myuser\n Port 2222\n IdentityFile ~/.ssh/id_rsa\n```\n\nThen use `\"host\": \"myserver\"` - the rest is resolved for you.\n\n## Credential Hiding (OVRD\\_\\*)\n\nFor production environments, store real credentials in env vars so AI agents only see aliases:\n\n| Variable | Description |\n| -------------------------- | ----------------------- |\n| `OVRD_{alias}_HOST` | Real hostname or IP |\n| `OVRD_{alias}_PORT` | SSH port |\n| `OVRD_{alias}_USER` | SSH username |\n| `OVRD_{alias}_PASS` | SSH password |\n| `OVRD_{alias}_KEY` | Path to SSH private key |\n| `OVRD_{alias}_SUDO_PASS` | Sudo password |\n| `OVRD_{alias}_ENABLE_PASS` | Enable password |\n\n**Example config:**\n\n```json\n{\n \"mcpServers\": {\n \"ssh-session\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"mcp-ssh-reloaded\", \"serve\", \"mcp\"],\n \"env\": {\n \"OVRD_prod_db_HOST\": \"192.168.1.100\",\n \"OVRD_prod_db_USER\": \"admin\",\n \"OVRD_prod_db_PASS\": \"secret123\",\n \"OVRD_prod_db_SUDO_PASS\": \"sudopass\"\n }\n }\n }\n}\n```\n\nThe agent uses `\"host\": \"prod_db\"` - never sees real IPs or passwords.\n\n## Configuration\n\n### Timeouts & server settings\n\nAll tunables live in `ServerConfig`. Values resolve in priority:\n\n1. **Constructor kwargs** (highest)\n2. **`MCP_SSH_*` environment variables**\n3. **Defaults** (lowest)\n\n| Env Variable | Default | Description |\n| ---------------------------------------- | --------------------------- | ----------------------------------- |\n| `MCP_SSH_DEFAULT_TIMEOUT` | `30` | Command timeout (seconds) |\n| `MCP_SSH_MAX_TIMEOUT` | `300` | Hard cap on timeout |\n| `MCP_SSH_CONNECT_TIMEOUT` | `30` | SSH connect timeout |\n| `MCP_SSH_MAX_WORKERS` | `10` | Thread pool size |\n| `MCP_SSH_MAX_FILE_BYTES` | `2097152` | Max file read/write (2 MB) |\n| `MCP_SSH_MAX_OUTPUT_BYTES` | `10485760` | Max command output (10 MB) |\n| `MCP_SSH_INTERACTIVE_MODE` | `true` | Enable PTY terminal emulation |\n| `MCP_SSH_PTY_AWARE_VALIDATION` | `false` | Relax validation for PTY inspection |\n| `MCP_SSH_MIKROTIK_AUTO_PAGING` | `true` | Auto-handle MikroTik pagers |\n| `MCP_SSH_TERMINAL_WIDTH` | `100` | PTY columns |\n| `MCP_SSH_TERMINAL_HEIGHT` | `24` | PTY rows |\n| `MCP_SSH_LOG_DIR` | `/tmp/mcp_ssh_session_logs` | Log directory |\n| `MCP_SSH_BACKGROUND_MONITOR_MAX_TIMEOUT` | `300` | Background monitor max timeout |\n| `MCP_SSH_NORMAL_IDLE_TIMEOUT` | `2` | Normal idle timeout (seconds) |\n| `MCP_SSH_PACKAGE_MANAGER_IDLE_TIMEOUT` | `10` | Package manager idle timeout |\n| `MCP_SSH_ASYNC_DEFAULT_TIMEOUT` | `30` | Async command default timeout |\n\n### Via CLI (serve modes)\n\n```bash\nmcp-ssh serve mcp --default-timeout 60 --max-workers 20\nmcp-ssh serve http --port 8080 --interactive-mode false\nmcp-ssh serve sse --port 9000 --connect-timeout 15\n```\n\n### Via API\n\n```python\nfrom mcp_ssh_reloaded import SSHService, ServerConfig\n\nsvc = SSHService(config=ServerConfig(default_timeout=60, max_timeout=600))\n```\n\n## How It Works\n\nCommands run inside persistent interactive shells:\n\n- **Directory persists**: `cd /tmp` stays in `/tmp` for the next command\n- **Env vars persist**: `export FOO=bar` is visible across commands\n- **Prompt detection**: completion detected via captured prompt or idle timeout (2 s)\n- **Session recovery**: stuck shells auto-reset after repeated prompt-detection failures\n\n## Testing\n\n```bash\n# unit tests only - the integration suites self-skip without SSH_TEST_HOST\nuv run pytest tests/\n\n# everything, against a real host\nSSH_TEST_HOST=myserver SSH_TEST_USER=admin SSH_TEST_PASSWORD=secret uv run pytest tests/\n\n# or spin up a throw-away sshd container (the same image CI uses)\ndocker build -t mcp-ssh-test .github/sshd-test\ndocker run -d --name sshd-test -p 127.0.0.1:2222:22 mcp-ssh-test\nSSH_TEST_HOST=127.0.0.1 SSH_TEST_PORT=2222 SSH_TEST_USER=root \\\nSSH_TEST_PASSWORD=rootpass SSH_TEST_SUDO_PASSWORD=rootpass \\\nuv run pytest tests/ --ignore=tests/test_mikrotik.py --ignore=tests/test_network_devices.py\n```\n\n`test_mikrotik.py` and `test_network_devices.py` need physical network gear.\n\n`.github/workflows/integration.yml` runs the container-backed suite on every\npull request; `.github/workflows/ci.yml` covers unit tests, pyright, ruff and\npackaging across Python 3.10-3.13.\n\n## Architecture\n\nTypes are declared in a single module (`models.py`); `api_types.py` and\n`datastructures.py` are backward-compatible re-export shims. All execution goes\nthrough one stack, `CommandExecutor`, which returns a structured\n`ExecutionResult`. See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for the\nmodule map, the execution pipeline and the known gaps.\n\n## Docs\n\n| Doc | Topic |\n| ---------------------------------------------------------- | ---------------------------------------------------------------------- |\n| [API-DOCS.md](./API-DOCS.md) | Full API reference - types, SSHService methods, MCP tools, error model |\n| [docs/AGENT_GUIDE.md](./docs/AGENT_GUIDE.md) | **Agent prompt** - patterns for correct tool usage, async handling |\n| [docs/ASYNC_COMMANDS.md](./docs/ASYNC_COMMANDS.md) | Smart execution & async command lifecycle |\n| [docs/INTERACTIVE_MODE.md](./docs/INTERACTIVE_MODE.md) | Terminal emulation, screen snapshots, key sending |\n| [docs/SAFETY_PROTECTIONS.md](./docs/SAFETY_PROTECTIONS.md) | Limits, timeouts, session recovery, error handling |\n| [docs/DOCKER.md](./docs/DOCKER.md) | Running via Docker |\n| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Module map, execution pipeline, known gaps |\n\n\n## License\n\nMIT - see [LICENSE](./LICENSE).\n\n## Fork\n\nFork of [devnullvoid/mcp-ssh-session](https://github.com/devnullvoid/mcp-ssh-session) with significant refactoring by [AmritaConstant](https://github.com/AmritaBot).\n"}