✨ hex-ssh-mcp — hash-verified remote file editing for AI agents over SSH

[levnikolaevich]

Your agent can read and edit local files — but what about the server running in production? When something breaks at 2 AM, the agent needs to check configs, search logs, and patch files on remote machines. Raw SSH commands flood context with noisy output — timestamps, UUIDs, and IPs that change on every run. And there's no way to verify that an edit landed on the right line of the right version of a remote file.

hex-ssh-mcp is an MCP server that brings hash-verified editing to remote machines over SSH. Every remote file read returns FNV-1a hash-annotated lines and range checksums — the same format as hex-line-mcp. Edits verify those checksums before applying changes. Command output is normalized and deduplicated automatically.

Tip

Same verification contract as hex-line, but across SSH boundaries. If the remote file changed since you last read it, the edit is rejected — not silently applied to the wrong version.

When it matters

🔍 "Check a config on the remote server"
Your agent needs to read the nginx config on production — 200 lines, but only the upstream block matters. With raw ssh cat /etc/nginx/nginx.conf, the entire file floods your context. With ssh-read-lines, the agent requests lines 40–80 with hash annotations. Each line carries an FNV-1a tag, ready for immediate editing — no second read needed.

Targeted partial read with edit-ready hashes. No full-file dump.

⚠️ "Fix a typo in production config"
The agent read the file 5 minutes ago and wants to fix a typo on line 65. But someone deployed a hotfix since then — lines shifted. With a raw SSH command, the edit silently overwrites the wrong line. hex-ssh's ssh-edit-block checks the range checksum before applying. Stale? Edit rejected, current checksum returned. The agent re-reads just the changed range and retries.

Zero silent overwrites across SSH boundaries.

📋 "Search remote logs for an error pattern"
The agent greps 10,000 lines of application logs looking for "connection timeout." Raw output: thousands of duplicate stack traces with different timestamps, UUIDs, and request IDs. ssh-search-code normalizes all dynamic values — UUIDs become <UUID>, timestamps become <TS>, IPs become <IP>. Identical normalized lines collapse with (xN) counts. 10K lines become ~60 actionable ones.

72% average noise reduction across normalization diagnostics.

🔒 "Write to a restricted path"
The agent generates a new config and writes it to the staging server. But a typo in the path targets /etc/ instead of /home/deploy/etc/. With raw SSH, the file lands in the system directory — potentially breaking the server. hex-ssh checks against ALLOWED_DIRS before every write. Path outside the permitted list? Rejected immediately.

Path validation prevents writes outside permitted directories.

Output normalization

Remote command output is noisy. hex-ssh cleans it up automatically:

Pattern	Replacement	Example
UUIDs	<UUID>	550e8400-e29b-41d4-... → <UUID>
Timestamps	<TS>	2026-03-19 14:30:00 → <TS>
IP addresses	<IP>	192.168.1.100:8080 → <IP>
Hex IDs	/<ID>	/a1b2c3d4e5 → /<ID>
Large numbers	<N>	1234567 → <N>

Pipeline: Normalize → Deduplicate (collapse identical lines with (xN)) → Truncate (keep first 40 + last 20).

Scenario	Input	Output	Savings
npm install output	11,219 ch	2,953 ch	74%
Server logs	19,715 ch	4,470 ch	77%
Grep results	5,799 ch	3,199 ch	45%
Large output (truncate)	22,281 ch	2,717 ch	88%

Average: 72% reduction (62,948 → 17,865 chars).

6 tools

Tool	What it does
ssh-read-lines	Read remote files with hash-annotated lines. Partial reads via startLine/endLine
ssh-edit-block	Hash-verified anchor edits. Checksum verification + compact diff
ssh-search-code	Search remote files with grep. Hash-annotated matches — search, then edit directly without re-reading
ssh-write-chunk	Write or append to remote files. Rewrite is atomic via temp+rename
ssh-verify	Check if held checksums are still valid. Single-line response
remote-ssh	Execute shell commands. Disabled by default; normalized output when enabled

Security — not optional when agents talk to production

Feature	What it does
Host Key Verification	Fail-closed — rejects connections unless fingerprint matches known_hosts or ALLOWED_HOST_FINGERPRINTS
ALLOWED_HOSTS	Comma-separated permitted hostnames/IPs. Unlisted hosts rejected
ALLOWED_DIRS	Comma-separated path prefixes. File ops outside these paths rejected
remote-ssh disabled	Raw shell execution off by default. Opt into safe or open explicitly
Command policy	safe mode blocks rm -rf /, mkfs, fork bombs, chmod 777, etc.
Shell escaping	All arguments single-quote escaped. Null bytes and newlines rejected
Exec timeout	Commands terminated after 120s
Key-only auth	No passwords — RSA, ED25519, ECDSA only
Atomic writes	rewrite uses temp file + rename; content is base64-encoded (no injection via content)

SSH config support

hex-ssh reads ~/.ssh/config automatically — use your aliases, not raw IPs:

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

Connections are pooled and reused (idle timeout 60s, max 10). Multi-key auth tries each IdentityFile in order, like OpenSSH.

Get started

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

Set ALLOWED_HOSTS to restrict which servers the agent can reach. Add ALLOWED_DIRS for path restrictions. Set REMOTE_SSH_MODE=safe if you want shell command execution.

Tip

If you use claude-code-skills, the /ln-010-dev-environment-setup skill installs all three hex MCP servers, configures hooks, and syncs settings across Claude, Gemini, and Codex in one pass.

Hex Family

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

---

Full docs: README · npm: @levnikolaevich/hex-ssh-mcp · Site: hex-ssh page

What remote operations eat the most tokens in your workflow? Let us know in the comments.