SSH

You run an MCP server that gives trusted, persistent SSH access to remote machines for MCP-compatible clients. It maintains live SSH sessions so you can run multi-step workflows, diagnostics, or long-running tasks while preserving environment state between commands.

How to use

Use an MCP client to manage hosts, start persistent SSH sessions, and execute commands inside those sessions. You register hosts once, then you can start a session for a host, run a sequence of commands, and close the session when you’re finished. Commands are executed in a shared interactive shell, so you can navigate directories, run pipelines, and maintain environment state across steps. When a command finishes, you receive the combined output up to a unique completion marker and information about the exit status.

How to install

Prerequisites: verify you have Node.js and npm installed on your system. You can use any supported shell.

Install the MCP server package globally so the ssh-mcp-sessions executable is available in your environment.

npm install -g ssh-mcp-sessions

Run the server from anywhere in your shell.

ssh-mcp-sessions

If you prefer a project-local setup, install in your project and run with npx.

npm install ssh-mcp-sessions
npx ssh-mcp-sessions

Configure your MCP client to connect to the local stdio server using the following command configuration.

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "npx",
      "args": [
        "ssh-mcp-sessions"
      ]
    }
  }
}

Host configuration and sessions

Set up target hosts that you want to manage through SSH. Hosts are stored in a local configuration file and are referenced by a unique host_id when starting sessions.

Typical operations include adding a host, listing hosts, starting a session for a host, executing commands in the session, listing active sessions, and closing sessions when done.

Session management

Start a session for a registered host to open a persistent SSH shell. You can then issue multiple commands without re-establishing the SSH connection.

List active sessions to monitor running shells and their recent activity.

Execute commands within a session to reuse the same SSH shell and keep the working directory and environment state.

Close a session to terminate the SSH connection and clean up resources.

Authentication modes

Password authentication stores the password in the host configuration and passes it to the SSH client during connection.

Private key authentication uses a keyPath from the host configuration. Keys may be encrypted; in that case you may need to provide a passphrase via an environment variable.

SSH agent forwarding acts as a fallback when neither password nor keyPath is provided and an SSH agent is available via SSH_AUTH_SOCK.

Timeouts & inactivity handling

Each session has a global inactivity timeout (default 2 hours). The timer resets when commands succeed. If the timer elapses, the session closes the SSH connection, shell, and buffers, and the session is removed from the active list.

Command completion uses a UUID marker to separate command output from the exit status.

Security considerations

Treat the host configuration file as sensitive because it may contain passwords or key paths. Prefer key-based authentication or SSH agent when possible and restrict permissions to avoid leaking credentials.

Troubleshooting

If a host_id already exists, choose a new ID or edit the existing host. If a host is missing, list hosts to confirm and then add it again. When a command fails remotely but the session remains open, inspect the output and consider adjusting the command or environment. Inactivity timeouts can be addressed by starting a new session or reducing idle time.

Using the MCP tools

The tools let you add hosts, start sessions, execute commands, list hosts, list sessions, and close sessions. Use the MCP client’s command palette or inspector integration to invoke these actions.

Testing

Run unit tests with your package manager’s test command if you include tests in your project.

Directory structure and files

The server runs from the ssh-mcp-sessions executable and stores host configurations in the local configuration directory used by the server. The runtime directory contains the compiled or built assets as needed by your installation.

Available tools

add-host

Add a new SSH target to the stored hosts configuration with a unique host_id and connection details.

list-hosts

Return a list of configured hosts with their connection parameters and authentication method.

start-session

Start a new persistent SSH session for a specified host_id and receive a session identifier.

list-sessions

Show all active SSH sessions with metadata such as host, uptime, and last executed command.

exec

Execute a command within an active session, returning the command output and exit status.

close-session

Close a specific active session identified by its sessionId.