hex-ssh-mcp

Token-efficient SSH MCP server with hash-verified remote file editing.

Every remote file read returns FNV-1a hash-annotated lines and range checksums. Edits verify those checksums before applying changes -- preventing stale-context corruption across SSH boundaries. Command output is normalized and deduplicated for minimal token usage. The MCP server itself runs on Windows, macOS, and Linux.

Features

8 MCP Tools

Output Normalization

Built into remote-ssh and ssh-search-code. Pipeline:

1. Normalize -- replaces UUIDs, timestamps, IPs, hex IDs, large numbers with placeholders
2. Deduplicate -- collapses identical normalized lines with (xN) counts
3. Truncate -- keeps first 40 + last 20 lines, omits the middle

Install

npm i -g @levnikolaevich/hex-ssh-mcp
claude mcp add -s user hex-ssh -e ALLOWED_HOSTS=server1,server2 -- hex-ssh-mcp

Requires Node.js >= 20.19.0.

Supported Remote Targets

• Host runtime: Windows, macOS, and Linux.
• Remote shell tools (remote-ssh, ssh-read-lines, ssh-edit-block, ssh-search-code, ssh-write-chunk, ssh-verify) expect a POSIX-style shell environment with standard coreutils (grep, sed, wc, base64).
• SFTP transfer tools (ssh-upload, ssh-download) support platform-aware remote paths via remotePlatform=auto|posix|windows.

SSH Config Support

hex-ssh automatically reads ~/.ssh/config to resolve host aliases, usernames, ports, and identity files. Just use your SSH alias:

host: "contabo"  // resolves HostName, User, Port, IdentityFile from config

Resolution Priority

Connection Reuse

Connections are pooled and reused across tool calls to the same host with the same auth identity. Idle connections close after 60 seconds. Max 10 pooled connections.

Environment Variables

Unsupported Directives (v1)

ProxyJump and ProxyCommand return an explicit UNSUPPORTED_SSH_CONFIG error. ssh2 does not support native proxy tunneling.

Multi-Key Auth

When SSH config provides multiple IdentityFile entries, hex-ssh tries each key in order (like OpenSSH). If the server rejects a key, the next one is attempted automatically.

Security

Host Key Verification

SSH host keys are verified against known fingerprints (fail-closed). Sources checked in order:

1. ALLOWED_HOST_FINGERPRINTS env -- comma-separated SHA256:<base64> values
2. ~/.ssh/known_hosts -- parsed, fingerprints computed from stored keys

If neither source has a match, the connection is rejected. Override known_hosts path with KNOWN_HOSTS_PATH env. Plain hostnames, hashed hostnames, and marker-prefixed known_hosts entries are parsed for fingerprint matching.

Shell Escaping

All user-supplied arguments (file paths, patterns, commands) are single-quote escaped before shell interpolation. Null bytes and newlines in arguments are rejected (UNSAFE_ARG error).

Command Policy (remote-ssh)

remote-ssh is disabled by default. Modes:

Dangerous patterns are blocked in safe mode:

Set REMOTE_SSH_MODE=safe or REMOTE_SSH_MODE=open explicitly to enable the tool.

Path Canonicalization

Remote paths must be absolute for their platform. POSIX paths use /...; Windows remote paths use drive-qualified forms such as C:\repo\file.txt and should set remotePlatform: "windows" when auto-detection would be ambiguous. . and .. segments are resolved before validation. Both file paths and ALLOWED_DIRS entries are canonicalized symmetrically.

Local transfer paths for ssh-upload and ssh-download must be absolute paths or ~/.... When ALLOWED_LOCAL_DIRS is set, local paths are canonicalized and checked against that allowlist before the transfer starts.

Per-call Timeouts

Timeout fields are scoped to the operation type. Missing or invalid values fall back to the default.

Priority for transferTimeoutMs: per-call arg > TRANSFER_TIMEOUT_MS env var > built-in default. The other timeout fields have no env override; pass the arg to change them.

Atomic File Writes

File content is base64-encoded for transfer (no shell injection via content).

• rewrite uses temp file + rename and is atomic
• append writes directly with >> and is not atomic

ALLOWED_HOSTS (recommended)

Comma-separated list of permitted hostnames/IPs. When set, connections to unlisted hosts are rejected.

ALLOWED_HOSTS=prod-web,prod-db,10.0.0.5

When unset, all hosts are permitted.

ALLOWED_DIRS (optional)

Comma-separated list of permitted remote directory prefixes. When set, file operations outside these paths are rejected.

ALLOWED_DIRS=/home/deploy,/var/www,/etc/nginx

When unset, all remote paths are permitted.

ALLOWED_LOCAL_DIRS (optional)

Comma-separated list of permitted local directory prefixes for ssh-upload and ssh-download. When set, local paths outside these directories are rejected before transfer.

ALLOWED_LOCAL_DIRS=/Users/alice/projects,/tmp/hex-ssh

When unset, any absolute local path is permitted.

MAX_TRANSFER_BYTES (optional)

Maximum allowed file size for ssh-upload and ssh-download. Transfers above the limit fail fast with FILE_TOO_LARGE.

MAX_TRANSFER_BYTES=134217728

TRANSFER_TIMEOUT_MS (optional)

Default transfer inactivity window for ssh-upload and ssh-download when no per-call transferTimeoutMs is supplied. If no transfer progress is observed before the timeout expires, the transfer fails with TRANSFER_TIMEOUT. Per-call transferTimeoutMs always overrides this. See "Per-call Timeouts" above.

TRANSFER_TIMEOUT_MS=120000

SSH Key Authentication

Key-only authentication (no passwords). Resolution order:

1. privateKeyPath tool parameter (explicit per-call)
2. SSH_PRIVATE_KEY env var (path or raw key content starting with -----)
3. Default paths: ~/.ssh/id_rsa, ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa

Supported key types: RSA, ED25519, ECDSA.

Tools Reference

remote-ssh

Execute shell commands on remote servers. Disabled by default; set REMOTE_SSH_MODE=safe or REMOTE_SSH_MODE=open to enable. Output is normalized and deduplicated when the tool runs.

ssh-read-lines

Read remote file with FNV-1a hash-annotated lines and range checksums. Always prefer over remote-ssh cat -- returns edit-ready hashes.

Output format:

File: /etc/nginx/nginx.conf (85 lines) [showing 1-50] (35 more below)

ab.1    worker_processes auto;
cd.2    error_log /var/log/nginx/error.log;
...
checksum: 1-50:f7e2a1b0

ssh-edit-block

Edit remote files using hash-verified anchors. Use ssh-read-lines first to get hash anchors and checksums.

Returns a compact diff of applied changes. If checksum is stale, returns an error with the current checksum.

ssh-search-code

Search remote files with grep. Results are deduplicated (identical normalized lines collapsed with (xN) counts).

ssh-write-chunk

Write content to remote files (rewrite or append). Creates parent directories. rewrite is atomic via temp file + rename; append is non-atomic direct append. For existing files, prefer ssh-edit-block (shows diff, verifies hashes).

ssh-upload

Upload a local file to the remote server over SFTP. Supports text and binary files. Creates remote parent directories over SFTP, stages to a temp file, then uses the strongest available finalize path (ext_openssh_fsync / ext_openssh_rename when supported, standard close+rename otherwise).

Success output includes bytes=, durationMs=, verify=, and durabilityPath=. Existing destinations are rejected unless overwrite=true. Oversized transfers fail before streaming based on MAX_TRANSFER_BYTES.

ssh-download

Download a remote file to the local machine over SFTP. Supports text and binary files. Writes to a temp file locally, fsyncs the staged file, then finalizes to the requested destination and verifies metadata when enabled.

Success output includes bytes=, durationMs=, verify=, and durabilityPath=. Existing destinations are rejected unless overwrite=true. When ALLOWED_LOCAL_DIRS is set, the destination must resolve inside that allowlist.

ssh-verify

Verify range checksums from prior ssh-read-lines calls without re-reading full content.

Returns a single-line confirmation when all valid, or lists changed ranges with current checksums.

Output Normalization

The shared @levnikolaevich/hex-common/output/normalize module reduces token waste in command output. It is applied automatically by remote-ssh and used internally by ssh-search-code.

Measurement Note

The repository currently ships only a normalization diagnostic for hex-ssh-mcp, not a public comparative benchmark against built-in tools. That diagnostic measures normalize/deduplicate/truncate efficiency on synthetic command-output fixtures and should not be presented as a real workflow benchmark.

Run it with:

npm run benchmark:diagnostic

Current normalization diagnostic sample:

Diagnostic summary: 72% average reduction (62,948 → 17,865 chars).

Interop Coverage

hex-ssh-mcp now has two transfer test layers:

• npm test runs fast smoke tests with mocked SSH/SFTP seams
• npm run test:interop runs real backend integration coverage

The interop suite validates:

• OpenSSH SFTP in Docker, including the opportunistic openssh-ext finalize path
• a controlled ssh2.Server fallback backend with no OpenSSH durability extensions

This means single-file ssh-upload / ssh-download behavior is covered across both the extension path and the standard fallback path. The interop suite requires Docker for the OpenSSH fixture.

Normalization Rules

Deduplication

Identical lines (after normalization) are collapsed into a single line with (xN) count, sorted by frequency descending.

Smart Truncation

Output exceeding 60 lines (40 head + 20 tail) is truncated with a gap indicator showing the number of omitted lines.

Architecture

hex-ssh-mcp/
  server.mjs          MCP server (stdio transport, 8 tools)
  package.json
  lib/
    ssh-client.mjs    SSH connection, host/path validation, key resolution
    transfer.mjs      Local path validation and SFTP upload/download helpers
    config-resolver.mjs SSH config parsing and host resolution
    command-policy.mjs Remote command safety policy

Shared substrate lives in `@levnikolaevich/hex-common`:

- `runtime/mcp-bootstrap`
- `runtime/schema`
- `runtime/results`
- `runtime/update-check`
- `text-protocol/hash`
- `output/normalize`

Hash Format

ab.42    const x = calculateTotal(items);

• ab -- 2-char FNV-1a tag derived from content (whitespace-normalized)
• 42 -- line number (1-indexed)
• Tab separator, then original content
• Tag alphabet: abcdefghijklmnopqrstuvwxyz234567 (32 symbols, bitwise selection)

Range Checksums

checksum: 1-50:f7e2a1b0

FNV-1a accumulator over all line hashes in the range (little-endian byte feed). Detects changes to any line, even ones not being edited.

FAQ

License

MIT