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

claude mcp add -s user hex-ssh -e ALLOWED_HOSTS=server1,server2 -- node path/to/mcp/hex-ssh-mcp/server.mjs

Then install dependencies:

cd mcp/hex-ssh-mcp && npm install

Requires Node.js >= 18.0.0.

Security

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. Output is normalized and deduplicated.

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 text blocks in remote files with optional hash verification. Use ssh-read-lines first to get 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. 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.

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.

Key differences:

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