mcp-ssh-sessions

Persistent SSH sessions as MCP tools for AI coding agents. Connect once, run commands across conversations.

Security Model

• SSH keys, passwords, and session metadata stay on the local machine running the MCP server.
• The server opens outbound SSH connections directly to your remote host. It does not proxy credentials through a third-party service.
• Host key verification is enabled by default using your local OpenSSH configuration and known_hosts files.
• Passwords are kept in memory only for the current process and are never written to the on-disk session store.

Quick Start

Claude Code

claude mcp add ssh -- npx -y mcp-ssh-sessions

Codex CLI (OpenAI)

codex mcp add ssh -- npx -y mcp-ssh-sessions

That's it. Both tools will auto-install and run the server on demand.

Features

• Persistent sessions — SSH connections survive across tool calls; reconnectable configs are saved locally to disk
• Strict host verification — resolves ~/.ssh/config with ssh -G and verifies remote host keys against local known_hosts
• Two execution modes — ssh_exec for stateless commands, ssh_shell for stateful shell workflows
• Stable shell framing — ssh_shell runs through a non-interactive persistent bash process to avoid prompt and MOTD corruption
• SFTP file transfer — ssh_upload and ssh_download transfer files over the active SSH session
• Auto-reconnect — transparently reconnects dropped key-based sessions and live password-based sessions within the same process
• Dual transport — stdio (default, per-process) or HTTP daemon (shared across terminals)
• 9 tools — ssh_connect, ssh_exec, ssh_shell, ssh_upload, ssh_download, ssh_sessions, ssh_reconnect, ssh_disconnect, ssh_set_default

Manual Configuration

Claude Code

In ~/.claude.json under mcpServers:

{
  "ssh": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "mcp-ssh-sessions"]
  }
}

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.ssh]
command = "npx"
args = ["-y", "mcp-ssh-sessions"]

HTTP Daemon Mode (shared sessions)

Run the daemon once so all terminals share the same SSH sessions:

npx mcp-ssh-sessions --http 7722

Then point your MCP client to SSE:

{
  "ssh": {
    "type": "sse",
    "url": "http://127.0.0.1:7722/mcp"
  }
}

Health check: curl http://127.0.0.1:7722/health

Tools

| Tool | Description | |------|-------------| | ssh_connect | Open a named SSH session. Resolves ~/.ssh/config with OpenSSH itself. | | ssh_exec | Run a command (fresh channel, no state). Returns stdout/stderr/exit code. | | ssh_shell | Run a command in a persistent non-interactive bash shell (keeps cwd/env state). | | ssh_upload | Upload a local file to the remote host over SFTP. | | ssh_download | Download a remote file to the local machine over SFTP. | | ssh_sessions | List all sessions (active, disconnected, saved). | | ssh_reconnect | Reconnect a dropped session from saved config. | | ssh_disconnect | Close a session. Pass forget=true to delete saved config. | | ssh_set_default | Set which session is used when no name is given. |

Usage Examples

Once the MCP server is running, your AI agent can use these tools:

ssh_connect(name: "myserver", host: "10.0.0.50")
ssh_exec(command: "docker ps")
ssh_upload(localPath: "./notes.txt", remotePath: "/tmp/notes.txt")
ssh_download(remotePath: "/var/log/syslog", localPath: "./syslog.txt")

# Stateful shell — cwd persists between calls
ssh_shell(command: "cd /var/log")
ssh_shell(command: "tail -20 syslog")

# Use an SSH config alias
ssh_connect(name: "plex", host: "plex")

# List all sessions
ssh_sessions()

Session Persistence

Connection configs are saved to ~/.ssh-mcp-sessions.json. This means:

• Sessions appear in ssh_sessions even after restart.
• ssh_reconnect can restore key-based sessions without re-entering credentials.
• Passwords are never saved to disk.
• Password-auth reconnect after process restart requires running ssh_connect again.

Testing

npm run check
npm run build

The test suite covers framed shell parsing, known_hosts verification including hashed entries, SSH config resolution, and reconnect decision behavior.

License

MIT