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.

Features

6 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 >= 18.0.0.

Supported Remote Targets

Linux/POSIX hosts with standard coreutils (grep, sed, wc, base64).

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. Note: v1 supports plain hostname entries only (hashed hostnames and @cert-authority markers are not parsed).

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

All remote paths must be absolute (start with /). .. segments are resolved before validation. Both file paths and ALLOWED_DIRS entries are canonicalized symmetrically.

Exec Timeout

SSH commands are terminated after 120 seconds (EXEC_TIMEOUT error).

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.

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-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 normalize.mjs module reduces token waste in command output. 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).

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, 6 tools)
  package.json
  lib/
    ssh-client.mjs    SSH connection, host/path validation, key resolution
    hash.mjs          FNV-1a hashing, 2-char tags, range checksums
    normalize.mjs     Output normalization, deduplication, truncation

Relationship to hex-line-mcp

Both servers share the same FNV-1a hash format and line annotation convention (tag.lineNum\tcontent). Checksums from ssh-read-lines are structurally identical to those from hex-line's read_file.

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

Hex Family

Package	Purpose	npm
hex-line-mcp	Local file editing with hash verification + hooks
hex-ssh-mcp	Remote file editing over SSH
hex-graph-mcp	Code knowledge graph with AST indexing

License

MIT