regolet-ssh-mcp

MCP (Model Context Protocol) server for remote SSH operations. Execute commands, transfer files, and manage SSH connections — all through AI agents, IDEs, or any MCP-compatible client.

Uses the ssh2 library (pure JavaScript, no native dependencies) with password authentication for reliable, secure connections.

Quick Start

npx regolet-ssh-mcp

Features

| Tool | Description | |------|-------------| | ssh_connect | Connect to a server (supports jump host / bastion tunneling) | | ssh_disconnect | Disconnect from a server | | ssh_execute | Execute shell commands with full stdout/stderr output | | ssh_upload | Write file content to the remote server (SFTP) | | ssh_download | Read file content from the remote server (SFTP) | | ssh_list_dir | List directory contents with permissions & sizes | | ssh_list_connections | List all active SSH connections | | ssh_status | Check connection status (shows jump host path if used) | | ssh_list_hosts | List all saved/configured SSH hosts | | ssh_find_host | Search hosts by name, description, or tags | | ssh_connect_host | Connect to a saved host by name (auto-uses jump host if configured) | | ssh_add_host | Save a host to the encrypted database (supports jump host config) | | ssh_remove_host | Remove a host from the encrypted database |

Jump Host / Bastion Support

Connect to servers behind a firewall through an intermediary (bastion/jump host). The connection is tunneled: Client → Jump Host → Target Server.

Direct connection with jump host

Tool: ssh_connect
Input: {
  "host": "10.0.0.50",
  "username": "admin",
  "password": "targetpass",
  "jumpHost": {
    "host": "bastion.mycompany.com",
    "username": "jumpuser",
    "password": "jumppass"
  }
}

Save a host with jump host (encrypted)

Tool: ssh_add_host
Input: {
  "name": "internal-db",
  "host": "10.0.0.50",
  "username": "admin",
  "password": "dbpass",
  "description": "Internal database behind bastion",
  "tags": ["database", "internal"],
  "jumpHost": {
    "host": "bastion.mycompany.com",
    "username": "jumpuser",
    "password": "jumppass"
  }
}

Then just connect by name — the jump host is used automatically:

Tool: ssh_connect_host
Input: { "name": "internal-db" }

Agent workflow with jump host

You: "Check the internal database server"

Agent → ssh_find_host("database")       → finds "internal-db" (jumpHost: jumpuser@bastion:22)
Agent → ssh_connect_host("internal-db") → tunnels through bastion automatically
Agent → ssh_execute("psql -c 'SELECT version()'")

Usage Examples

Save a host (encrypted)

Tool: ssh_add_host
Input: { "name": "router", "host": "192.168.1.1", "username": "root", 
         "password": "pass123", "description": "OpenWrt Router", 
         "tags": ["network", "firewall"] }

Connect by name

Tool: ssh_connect_host
Input: { "name": "router" }

Execute a command

Tool: ssh_execute
Input: { "command": "uptime && df -h" }

Read a config file

Tool: ssh_download
Input: { "remotePath": "/etc/nginx/nginx.conf" }

Write a file

Tool: ssh_upload
Input: { "remotePath": "/tmp/deploy.sh", "content": "#!/bin/bash\necho 'deploying...'" }

Search for a server

Tool: ssh_find_host
Input: { "query": "database" }

Development

git clone https://github.com/youruser/regolet-ssh-mcp.git
cd regolet-ssh-mcp
npm install
node bin/cli.js

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node bin/cli.js

Security

| Feature | Detail | |---------|--------| | Encrypted storage | Passwords stored in ~/.regolet-ssh/hosts.enc with AES-256-GCM | | Zero-config passwords | MCP config file contains no credentials when using encrypted database | | No command injection | Pure JS ssh2 library — no shell exec | | Jump host tunneling | Bastion connections use SSH forwardOut — no port exposure | | No network ports | Server communicates via stdio only | | Password-free output | ssh_list_hosts and ssh_find_host never expose passwords | | Configurable timeouts | Commands have timeouts to prevent hanging | | Input validation | All tool parameters validated via Zod schemas | | File permissions | Database file created with chmod 600 (owner-only read/write) |

License

MIT