@enrichedlab/mcp-ssh

SSH MCP server with real-time streaming, dual logging, and snapshots.

Disclaimer: This software is provided for testing, research, and development purposes only. It is not intended for production or enterprise use. Use at your own risk. The authors assume no liability for data loss, security incidents, or any damages resulting from use of this software. Review the source code before running.

Note: MCP servers can execute code on your machines. Only install from sources you trust and have reviewed - including this one. The source is available in this repo; read it before running.

Features

• Real-time streaming - Output streams back as commands run, not after completion
• Hang detection - Get alerted when something's stuck or waiting for input
• Dual logging - Commands logged on remote server AND local machine
• Snapshots - Git-first snapshots with tar fallback for file rollback
• Multi-host - Manage multiple Linux servers from one MCP
• Background jobs - Start long commands, check status later
• SFTP - Upload, download, list remote files

Quick Start

Run the interactive setup wizard:

npx @enrichedlab/mcp-ssh --setup

This will:

1. Create ~/.enrichedlab/ config directory
2. Generate SSH key (~/.ssh/enrichedlab_key)
3. Prompt for your server details
4. Copy SSH key to your servers
5. Create the config file
6. Test connections

Then add to Claude:

claude mcp add --scope user enrichedlab-ssh -- npx @enrichedlab/mcp-ssh

Manual Setup

1. Create config file

~/.enrichedlab/ssh-config.json:

{
  "hosts": {
    "dev": {
      "host": "10.0.0.1",
      "user": "llmuser",
      "keyPath": "~/.ssh/id_ed25519"
    },
    "prod": {
      "host": "10.0.0.2",
      "user": "llmuser",
      "keyPath": "~/.ssh/id_ed25519"
    }
  },
  "defaultHost": "dev",
  "streaming": {
    "enabled": true,
    "hangTimeoutMs": 30000,
    "progressPatterns": true
  },
  "logging": {
    "localPath": "~/.enrichedlab/logs",
    "remotePath": "~/.enrichedlab"
  },
  "snapshots": {
    "enabled": true,
    "trackedPaths": ["/home/llmuser/code"],
    "autoSnapshotOnUpload": true,
    "autoSnapshotOnExec": false,
    "retention": {
      "maxAgeDays": 14,
      "maxSizeMB": 500,
      "keepMinCount": 10
    }
  }
}

2. Add to Claude Code

claude mcp add --scope user enrichedlab-ssh -- npx @enrichedlab/mcp-ssh

Or with explicit config path:

claude mcp add --scope user enrichedlab-ssh -- npx @enrichedlab/mcp-ssh ~/.enrichedlab/ssh-config.json

Tools

Core

| Tool | Description | |------|-------------| | exec | Run command with streaming output and hang detection | | list_hosts | Show configured hosts and connection status |

Background Jobs

| Tool | Description | |------|-------------| | job_start | Start a command as a background job | | job_status | Get status of a background job | | job_output | Get output from a background job | | job_list | List all background jobs | | job_kill | Terminate a running job |

File Operations

| Tool | Description | |------|-------------| | file_upload | Upload file via SFTP (auto-snapshots existing) | | file_download | Download file via SFTP | | file_list | List remote directory contents |

Snapshots

| Tool | Description | |------|-------------| | snapshot_create | Manually create a snapshot | | snapshot_list | List available snapshots | | snapshot_restore | Restore from a snapshot | | snapshot_cleanup | Clean old snapshots | | snapshot_archives | List compressed metadata archives | | snapshot_import | Import entries from an archive back into active list |

Snapshot metadata auto-compacts when the metadata file exceeds 1MB. Old entries are compressed to .archived.gz files under ~/.enrichedlab/logs/snapshots/archives/. Use snapshot_archives and snapshot_import to access historical snapshots.

Security

• Host key verification: Enabled by default (TOFU - Trust On First Use). On first connection, the server's host key is recorded in ~/.ssh/known_hosts. Subsequent connections verify the key matches. A mismatch (possible MITM) rejects the connection with a clear error.
• Config permissions: The server rejects config files with group/world-readable permissions. Setup creates files with 0600 and directories with 0700.
• Sudo: The sudo_exec tool (when enabled) checks commands against a regex-based blocklist and optionally an allowlist. These are advisory safeguards only. Real access control must be enforced via sudoers on the remote host. The operator is responsible for commands executed with sudo.
• Audit logging: All commands are logged locally and remotely. Audit logs may contain up to 500 chars of command output. Avoid running commands that print secrets to stdout.
• File operations: Can access any path the SSH user has permissions for. Use a dedicated SSH user with restricted access for production hosts.

Config Reference

hosts

{
  "myhost": {
    "host": "10.0.0.1",
    "port": 22,
    "user": "llmuser",
    "keyPath": "~/.ssh/id_ed25519"
  }
}

• keyPath - SSH private key (required, key-based auth only)

streaming

{
  "enabled": true,
  "hangTimeoutMs": 30000,
  "progressPatterns": true
}

• hangTimeoutMs - Alert after this many ms of no output
• progressPatterns - Parse Docker/npm/apt progress

snapshots

{
  "enabled": true,
  "trackedPaths": ["/home/llmuser/code"],
  "autoSnapshotOnUpload": true,
  "autoSnapshotOnExec": false,
  "retention": {
    "maxAgeDays": 14,
    "maxSizeMB": 500,
    "keepMinCount": 10
  }
}

• trackedPaths - Directories to snapshot before exec (if autoSnapshotOnExec)
• autoSnapshotOnUpload - Backup files before SFTP upload overwrites them
• Git directories use git commits, others use tar

security (optional)

{
  "strictHostKeyChecking": true,
  "knownHostsPath": "~/.ssh/known_hosts"
}

• strictHostKeyChecking - Verify host keys against known_hosts (default: true)
• knownHostsPath - Path to known_hosts file (default: ~/.ssh/known_hosts)

Set strictHostKeyChecking: false only for testing. In production, leave it enabled.

sudo (optional)

{
  "enabled": false,
  "blockedPatterns": ["rm\\s+-[^\\s]*r[^\\s]*f[^\\s]*\\s+/", "mkfs", "dd\\s+if="],
  "allowedCommands": ["systemctl", "journalctl", "apt"]
}

• enabled - Must be explicitly set to true to enable sudo_exec
• blockedPatterns - Regex patterns to reject (case-insensitive). Advisory only.
• allowedCommands - If set, only these command prefixes are allowed. If omitted, all commands pass (subject to blocklist).

The blocklist and allowlist are convenience guardrails. Real privilege control must be enforced through sudoers on the remote host.

Logging

Commands logged to two places:

Remote: ~/.enrichedlab/audit.log on each host Local: ~/.enrichedlab/logs/{hostname}/audit.log

Format is JSONL:

{"ts":"2026-01-14T10:30:45Z","host":"dev","cmd":"docker ps","exit":0,"duration_ms":234}

Examples

# Run command on default host
exec command="docker ps"

# Run on specific host
exec host="prod" command="systemctl status nginx"

# Start background build
job_start command="docker build -t myapp ." name="build-myapp"

# Check job status
job_status jobId="job_abc123"

# Get last 50 lines of output
job_output jobId="job_abc123" tail=50

# Upload config file
file_upload localPath="/tmp/nginx.conf" remotePath="/etc/nginx/nginx.conf"

# Create snapshot before risky operation
snapshot_create path="/home/llmuser/myproject"

# List snapshots
snapshot_list limit=10

# Restore if something went wrong
snapshot_restore snapshotId="snap_xyz789"

CLI Commands

# First-time setup (interactive wizard)
npx @enrichedlab/mcp-ssh --setup

# Add another host to existing config
npx @enrichedlab/mcp-ssh --add-host

# Start MCP server (default config)
npx @enrichedlab/mcp-ssh

# Start with custom config
npx @enrichedlab/mcp-ssh ~/my-config.json

# Show help
npx @enrichedlab/mcp-ssh --help

License

MIT