# SSH Session MCP (npm · ssh-session-mcp)

Shared SSH PTY runtime for MCP clients with viewer, input lock, async tracking, and policy rules.

- Trust score: 80/100 (high trust)
- Change this week: +34
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `ssh-session-mcp`: 80/100 (this document), [markdown](https://verifymcp.io/servers/zw-awa-ssh-session-mcp/ssh-session-mcp.md), [page](https://verifymcp.io/servers/zw-awa-ssh-session-mcp/ssh-session-mcp)

## Channel facts

- Registry: `npm`
- Package: `ssh-session-mcp`
- Version: `2.7.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (104 of 108), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (104 of 108), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to Zw-awa/ssh-session-mcp).
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 68 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 77/100
  - AI-judged instruction clarity (excellent).
  - Tool/resource definitions use about 2348 tokens (~102/item across 23 items; 23 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add zw-awa-ssh-session-mcp -- npx -y ssh-session-mcp
```

### Codex

```bash
codex mcp add zw-awa-ssh-session-mcp -- npx -y ssh-session-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "zw-awa-ssh-session-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "ssh-session-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add zw-awa-ssh-session-mcp --command npx --arg -y --arg ssh-session-mcp
```

### Hermes

```yaml
mcp_servers:
  zw-awa-ssh-session-mcp:
    command: "npx"
    args: ["-y", "ssh-session-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "zw-awa-ssh-session-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-session-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 80, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-02 (score 79, +58)

- [security improvement] Install scripts: unverified → pass
- [security improvement] Provenance: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [security] The attested source repository moved: Zw-awa/ssh-session-mcp
- [functional improvement] Stability: unverified → 0.23
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] License: unverified → pass
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] MCP protocol: unverified → pass
- [functional] Licence: Apache-2.0

### 2026-08-01 (score 21, −7)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 28, −18)

- [security regression] Malware scan: pass → unverified

### 2026-07-29 (score 46, +22)

- [functional improvement] Tool coverage: unverified → 100

### 2026-07-28 (score 24, −22)

- [functional regression] Tool coverage: 100 → unverified
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 46)

First indexed and scored.

## MCP tools (23)

### `ssh-session-open` (~460 tokens)

Open a persistent interactive SSH PTY session with automatic idle cleanup and a terminal-style dashboard view.

Input parameters:

- `autoOpenViewer` (boolean): Automatically ensure a local viewer is opened for this session
- `closedRetentionMs` (integer): How long to keep a closed session summary/transcript in memory before pruning
- `cols` (integer): PTY column count
- `connectionName` (string): Logical connection name for the selected device
- `dashboardHeight` (integer): Rendered dashboard height in rows
- `dashboardLeftChars` (integer): How many recent transcript chars to retain in the rendered viewer
- `dashboardRightEvents` (integer): How many recent input/control/lifecycle events to retain for actor markers
- `dashboardWidth` (integer): Rendered dashboard width in columns
- `device` (string): Device profile id from ssh-session-mcp.config.json
- `host` (string): SSH host. Falls back to server --host if omitted
- `idleTimeoutMs` (integer): Auto-close the SSH session after this much inactivity. 0 disables idle cleanup
- `includeDashboard` (boolean): Include the rendered dashboard text in the tool response
- `key` (string): Path to a private SSH key on the local machine
- `password` (string): SSH password
- `port` (integer): SSH port. Falls back to server --port or 22
- `rows` (integer): PTY row count
- `sessionName` (string): Optional human-readable alias for the session
- `startupInput` (string): Raw text to send immediately after opening the session
- `startupInputActor` (string): Actor label for startupInput, e.g. codex, claude, user
- `startupWaitMs` (integer): How long to wait before capturing the initial dashboard
- `stripAnsiFromLeft` (boolean): Strip ANSI escape sequences from rendered SSH output
- `term` (string): PTY TERM value
- `user` (string): SSH username. Falls back to server --user if omitted
- `viewerMode` (string): Viewer launch mode when autoOpenViewer is enabled
- `viewerSingletonScope` (string): How viewer singleton deduplication is scoped when autoOpenViewer is enabled

### `ssh-session-send` (~108 tokens)

Send raw input to an interactive SSH PTY session. Actor is shown inline in the dashboard transcript.

Input parameters:

- `actor` (string): Label for the sender shown inline in the dashboard, e.g. codex, claude, user
- `appendNewline` (boolean): Append a newline after the input
- `input` (string, required): Raw text to send into the PTY
- `session` (string): Session id, session ref, or session name. Defaults to the active session

### `ssh-device-list` (~23 tokens)

List configured SSH device profiles discovered from ssh-session-mcp.config.json.

### `ssh-session-read` (~108 tokens)

Read raw buffered terminal output from an SSH PTY session. Supports optional long-polling for new terminal output.

Input parameters:

- `maxChars` (integer): Maximum chars to return
- `offset` (integer): Read from this output offset. If omitted, return the latest tail
- `session` (string): Session id, session ref, or session name. Defaults to the active session
- `waitForChangeMs` (integer): Wait up to this many milliseconds for new terminal output before returning

### `ssh-session-watch` (~204 tokens)

Long-poll an SSH PTY session and render a terminal-style dashboard with inline actor markers.

Input parameters:

- `dashboardHeight` (integer): Rendered dashboard height in rows
- `dashboardLeftChars` (integer): How many recent transcript chars to retain in the rendered viewer
- `dashboardRightEvents` (integer): How many recent input/control/lifecycle events to retain for actor markers
- `dashboardWidth` (integer): Rendered dashboard width in columns
- `eventSeq` (integer): Wait until transcript events grow beyond this sequence number
- `includeDashboard` (boolean): Include the rendered dashboard text in the tool response
- `outputOffset` (integer): Wait until terminal output grows beyond this offset
- `session` (string): Session id, session ref, or session name. Defaults to the active session
- `stripAnsiFromLeft` (boolean): Strip ANSI escape sequences from rendered SSH output
- `waitForChangeMs` (integer): Long-poll duration in milliseconds

### `ssh-session-history` (~75 tokens)

Read line-numbered session history built from terminal output and user/agent actions.

Input parameters:

- `line` (integer): Read from this history line number
- `maxLines` (integer): Maximum number of history lines to return
- `session` (string): Session id, session ref, or session name. Defaults to the active session

### `ssh-session-control` (~90 tokens)

Send a control key to an interactive SSH PTY session. Actor is shown inline in the dashboard transcript.

Input parameters:

- `actor` (string): Label for the sender shown inline in the dashboard, e.g. codex, claude, user
- `control` (string, required): Control key to send
- `session` (string): Session id, session ref, or session name. Defaults to the active session

### `ssh-session-resize` (~63 tokens)

Resize the PTY window of an interactive SSH session.

Input parameters:

- `cols` (integer, required): New column count
- `rows` (integer, required): New row count
- `session` (string): Session id, session ref, or session name. Defaults to the active session

### `ssh-session-list` (~65 tokens)

List tracked SSH PTY sessions. Closed sessions are kept briefly for inspection, then automatically pruned.

Input parameters:

- `connectionName` (string): Filter by connection name
- `device` (string): Filter by device id
- `includeClosed` (boolean): Include recently closed retained sessions

### `ssh-session-diagnostics` (~52 tokens)

Inspect session health, buffer trim state, viewer attachment state, input lock state, and tracked command metadata.

Input parameters:

- `session` (string): Session id or unique session name. Omit to inspect all tracked sessions

### `ssh-session-policy-list` (~48 tokens)

List the inherited and session-level custom policy rules currently active for an SSH session.

Input parameters:

- `session` (string): Session id, session ref, or session name. Defaults to the active session

### `ssh-session-policy-upsert` (~206 tokens)

Add or update a session-level custom policy rule. Session rules are applied after immutable built-in hard blocks and before the built-in safe/full warning set.

Input parameters:

- `action` (string, required): block rejects the command, warn allows it with warning metadata
- `category` (string, required): Rule category shown in blocked/warned responses
- `enabled` (boolean): Whether the rule is active. Defaults to true
- `flags` (string): Optional JavaScript regex flags, for example i or gi
- `id` (string, required): Stable rule id used for future updates or removal
- `message` (string, required): Human-readable reason shown when the rule matches
- `mode` (string): Which operation mode the rule applies to
- `pattern` (string, required): JavaScript regular expression source without surrounding slashes
- `session` (string): Session id, session ref, or session name. Defaults to the active session
- `suggestion` (string): Optional remediation hint shown alongside the message

### `ssh-session-policy-remove` (~59 tokens)

Remove a session-level custom policy rule by id.

Input parameters:

- `id` (string, required): Rule id to remove from the current session rule set
- `session` (string): Session id, session ref, or session name. Defaults to the active session

### `ssh-session-policy-reset` (~48 tokens)

Reset the current session custom policy rules back to the inherited defaults loaded from configuration.

Input parameters:

- `session` (string): Session id, session ref, or session name. Defaults to the active session

### `ssh-session-set-active` (~50 tokens)

Set or clear the active session used by tools when the session argument is omitted.

Input parameters:

- `session` (string): Session id, session ref, or session name. Omit to clear the active session

### `ssh-viewer-ensure` (~84 tokens)

Ensure that a viewer exists for a session. Terminal mode is singleton-scoped and will reuse a running viewer instead of opening duplicates.

Input parameters:

- `mode` (string): Viewer launch mode
- `session` (string): Session id, session ref, or session name. Defaults to the active session
- `singletonScope` (string): Deduplication scope for terminal viewers

### `ssh-viewer-list` (~21 tokens)

List persisted local viewer processes and their current binding state.

### `ssh-session-close` (~47 tokens)

Close an interactive SSH PTY session immediately and remove it from the MCP server.

Input parameters:

- `session` (string): Session id, session ref, or session name. Defaults to the active session

### `ssh-quick-connect` (~101 tokens)

One-step: open SSH session using configured device profiles when available, otherwise fall back to legacy .env defaults. Reuse an existing session when possible and return viewer details when enabled.

Input parameters:

- `connectionName` (string): Logical connection name. Defaults to "main" for profile-based sessions
- `device` (string): Device profile id. Defaults to config defaultDevice when available
- `sessionName` (string): Optional session name. Defaults to "default"

### `ssh-run` (~178 tokens)

Execute a command in the SSH session and return the output. Uses intelligent completion detection (prompt matching + idle timeout). In safe mode, dangerous/interactive commands are blocked. Long-running commands automatically transition to async mode.

Input parameters:

- `command` (string, required): Shell command to execute
- `idleMs` (integer): Idle timeout in ms - if no new output for this duration, consider command done (default 2000)
- `maxChars` (integer): Max chars to read from output (default 16000). When output exceeds this limit, head (30%) and tail (70%) are returned with the middle omitted.
- `session` (string): Session name or id. Defaults to "default"
- `waitMs` (integer): Maximum wait time in ms (default 30000). Command may return earlier if prompt detected or idle timeout reached.

### `ssh-status` (~33 tokens)

Quick status check: list active sessions, viewer URL, connection state. Use this to check if a session is already running.

### `ssh-command-status` (~67 tokens)

Check the status of a long-running async command. Returns current output if completed, or partial output if still running.

Input parameters:

- `commandId` (string, required): The async command ID returned by ssh-run
- `maxChars` (integer): Max chars to read from output (default 16000)

### `ssh-retry` (~158 tokens)

Execute a command with automatic retry and backoff on failure. Useful for flaky network commands or services that need time to start.

Input parameters:

- `backoff` (string): Backoff strategy (default "exponential")
- `command` (string, required): Shell command to execute
- `delayMs` (integer): Base delay between retries in ms (default 1000)
- `failPattern` (string): Regex pattern - if output matches this, consider command failed regardless of exit code
- `maxRetries` (integer): Maximum number of retries (default 3)
- `session` (string): Session name or id. Defaults to "default"
- `successPattern` (string): Regex pattern - if output matches this, consider command successful regardless of exit code

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/zw-awa-ssh-session-mcp/ssh-session-mcp#diagnostics

## Score history

- 2026-08-03: 80
- 2026-08-02: 79
- 2026-08-01: 21
- 2026-07-31: 28
- 2026-07-29: 46
- 2026-07-28: 24
- 2026-07-27: 46

## Links

- npm package: https://www.npmjs.com/package/ssh-session-mcp
- Socket report: https://socket.dev/npm/package/ssh-session-mcp
- Repository: https://github.com/Zw-awa/ssh-session-mcp
- Website: https://zw-awa.github.io/ssh-session-mcp/
- Changelog RSS feed: https://verifymcp.io/servers/zw-awa-ssh-session-mcp/ssh-session-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/zw-awa-ssh-session-mcp/ssh-session-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/zw-awa-ssh-session-mcp/ssh-session-mcp