sshmcp

module
v0.0.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 21, 2025 License: MIT

README ยถ 

 $$$$$$\   $$$$$$\  $$\   $$\ $$\      $$\  $$$$$$\  $$$$$$$\
$$  __$$\ $$  __$$\ $$ |  $$ |$$$\    $$$ |$$  __$$\ $$  __$$\
$$ /  \__|$$ /  \__|$$ |  $$ |$$$$\  $$$$ |$$ /  \__|$$ |  $$ |
\$$$$$$\  \$$$$$$\  $$$$$$$$ |$$\$$\$$ $$ |$$ |      $$$$$$$  |
 \____$$\  \____$$\ $$  __$$ |$$ \$$$  $$ |$$ |      $$  ____/
$$\   $$ |$$\   $$ |$$ |  $$ |$$ |\$  /$$ |$$ |  $$\ $$ |
\$$$$$$  |\$$$$$$  |$$ |  $$ |$$ | \_/ $$ |\$$$$$$  |$$ |
 \______/  \______/ \__|  \__|\__|     \__| \______/ \__|


Secure SSH & SFTP Client with MCP Protocol Support

SSHMCP

sshx provides a barrier-free SSH command-line client while implementing the MCP (Model Context Protocol) interface, enabling AI assistants to easily invoke remote SSH/SFTP functionality.

Why You Need It?

Managing multiple servers means juggling different passwords, repeatedly entering sudo passwords, and manually executing SSH commands in AI assistants. sshx securely stores passwords in your system keyring, auto-fills sudo passwords, and enables AI assistants to directly operate remote servers through MCP protocol. One command, multiple servers, zero password hassle.

New! Host Configuration Management - Store your frequently used host configurations in ~/.sshmcp/settings.json and connect with just a name instead of typing full connection details every time. Import from your existing ~/.ssh/config or add hosts interactively!

Project Structure

  • cmd/sshx: Main binary entry point, responsible for command-line argument parsing, MCP mode startup, and password management features.
  • internal/sshclient: Core SSH/SFTP/script execution logic, command security validation, and connection pool wrapper.
  • internal/mcp: MCP stdio server implementation, exposing SSH/SFTP/script tools to external tools (e.g., AI assistants).

Key Features

  1. Cross-platform SSH/SFTP operations (supports sudo auto-fill).
  2. Password management (Keychain / Secret Service / Credential Manager).
  3. MCP stdio mode for AI assistant integration.
  4. Connection pooling, script execution, and command security validation.

Installation

If you have Go 1.21+ installed, you can use Go's built-in tools:

Run directly without installation (like npx)
# Run the latest version
go run github.com/talkincode/sshmcp/cmd/sshx@latest --help

# Run specific version
go run github.com/talkincode/sshmcp/cmd/sshx@v0.0.6 -h=192.168.1.100 "uptime"
Install globally
# Install latest version to $GOPATH/bin
go install github.com/talkincode/sshmcp/cmd/sshx@latest

# Then use it anywhere
sshx --help
sshx -h=192.168.1.100 "uptime"

Note: Make sure $GOPATH/bin (typically ~/go/bin) is in your PATH.

One-Line Installation Script
Linux / macOS
curl -fsSL https://raw.githubusercontent.com/talkincode/sshmcp/main/install.sh | bash

Or download and run:

wget https://raw.githubusercontent.com/talkincode/sshmcp/main/install.sh
chmod +x install.sh
./install.sh

Install specific version:

./install.sh v0.0.2
Windows

Open PowerShell as Administrator and run:

irm https://raw.githubusercontent.com/talkincode/sshmcp/main/install.ps1 | iex

Or download and run:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/talkincode/sshmcp/main/install.ps1" -OutFile "install.ps1"
.\install.ps1

Install specific version:

.\install.ps1 -Version v0.0.2
Manual Installation

Download pre-built binaries from Releases:

Linux / macOS:

# Download and extract (replace <platform>-<arch> with your system)
tar -xzf sshx-<platform>-<arch>.tar.gz

# Move to system path
sudo mv sshx /usr/local/bin/

# Make executable
sudo chmod +x /usr/local/bin/sshx

# Verify installation
sshx --help

Windows:

  1. Download sshx-windows-amd64.zip
  2. Extract the archive
  3. Move sshx.exe to a directory in your PATH (e.g., C:\Program Files\sshx)
  4. Or add the extracted directory to your system PATH
Build from Source
# Clone repository
git clone https://github.com/talkincode/sshmcp.git
cd sshmcp

# Build command-line tool
go build -o bin/sshx ./cmd/sshx

# Install to system (optional)
make install

Quick Start

# Execute remote command
sshx -h=192.168.1.100 -u=root "uptime"

# Save password for easier access (interactive input)
sshx --password-set=root

# Or set password for specific host
sshx --password-set=192.168.1.100-root

# Execute command without password flag (uses saved password)
sshx -h=192.168.1.100 -u=root "df -h"

# Start MCP stdio mode
sshx mcp-stdio

Host Configuration Management

NEW! Manage your frequently used hosts in ~/.sshmcp/settings.json for quick access.

Quick Setup
# Import hosts from your existing ~/.ssh/config
sshx --host-import

# Or add hosts interactively
sshx --host-add

# Add host with command line options
sshx --host-add --host-name=prod-web -h=192.168.1.100 -u=root --host-desc="Production Web Server"

# List all configured hosts
sshx --host-list

# Test connection to a configured host
sshx --host-test=prod-web

# Use configured host (auto-resolves from settings)
sshx -h=prod-web "systemctl status nginx"

# Test every configured host and show auth methods
sshx --host-test-all
Configuration File Format

Location: ~/.sshmcp/settings.json

{
  "key": "/Users/username/.ssh/id_rsa",
  "hosts": [
    {
      "name": "prod-web",
      "description": "Production Web Server",
      "host": "192.168.1.100",
      "port": "22",
      "user": "root",
      "password_key": "prod-web-password",
      "type": "linux"
    }
  ]
}
Host Management Commands
  • --host-add - Add new host (interactive or with options)
  • --host-import - Import hosts from ~/.ssh/config
  • --host-list - List all configured hosts
  • --host-test=<name> - Test connection to a host
  • --host-test-all - Test connections to all hosts (per-host 10s dial timeout) and show auth method used
  • --host-remove=<name> - Remove a host from configuration

Benefits:

  • ๐Ÿ“ Store connection details once, use everywhere
  • ๐Ÿš€ Connect with just a name: sshx -h=prod-web "command"
  • ๐Ÿ”„ Import from existing ~/.ssh/config
  • ๐Ÿ” Integrate with password manager for each host
  • โœ… Test connections before use

Password Management

sshx provides secure password storage using the operating system's native credential manager, eliminating the need to enter passwords repeatedly or store them in plaintext.

Supported Platforms
  • macOS: Uses Keychain Access
  • Linux: Uses Secret Service (GNOME Keyring / KDE Wallet)
  • Windows: Uses Credential Manager
Password Commands
Save Password
# Save default sudo password (interactive input, recommended)
sshx --password-set=master

# Save password for specific user
sshx --password-set=root

# Save password for specific host+user combination
sshx --password-set=192.168.1.100-root

# Set password inline (not recommended, insecure)
sshx --password-set=master:yourpassword

You will be prompted to enter the password securely (input is hidden).

Check Saved Password
# Check if password exists
sshx --password-check=master
sshx --password-check=root

# Output example:
# โœ“ Password exists for key: master
List Saved Passwords
# List common password keys
sshx --password-list

# Output example:
# Checking password keys in system keyring...
# Service: sshx
#
# Common keys:
#   โœ“ master (exists)
#   โœ“ root (exists)
#     sudo (not set)
Get Password
# Get stored password (for debugging)
sshx --password-get=master

# Output example:
# โœ“ Password retrieved from system keyring
#   Service: sshx
#   Key: master
#
# Password: yourpassword
Delete Password
# Delete password
sshx --password-delete=master
sshx --password-delete=root

# Confirmation message:
# โœ“ Password deleted from system keyring
#   Service: sshx
#   Key: master
Using Stored Passwords

Once a password is saved, sudo commands will automatically retrieve the password from system keyring:

# 1. First save sudo password
sshx --password-set=master

# 2. Execute sudo commands (automatically uses stored password)
sshx -h=192.168.1.100 -u=root "sudo systemctl status nginx"
sshx -h=192.168.1.100 -u=root "sudo reboot"

# 3. Multi-server scenario: save different passwords for different servers
sshx --password-set=server-A
sshx --password-set=server-B
sshx --password-set=server-C

# 4. Use -pk parameter to specify sudo password key temporarily
sshx -h=192.168.1.100 -pk=server-A "sudo systemctl restart nginx"
sshx -h=192.168.1.101 -pk=server-B "sudo systemctl restart nginx"
sshx -h=192.168.1.102 -pk=server-C "sudo systemctl restart nginx"

Host Key Verification ๐Ÿ”

sshx now enforces strict host key verification just like the OpenSSH client. Instead of silently trusting unknown hosts, the tool reads the trust store from ~/.ssh/known_hosts (or the path you provide) and aborts the connection if the host is missing or the key changes.

Ways to manage host keys:

  • Add hosts manually (recommended): ssh-keyscan -H <host> >> ~/.ssh/known_hosts
  • One-time automatic trust: sshx --accept-unknown-host -h=<host> ... (or set SSH_ACCEPT_UNKNOWN_HOST=1). The first connection records the key; subsequent runs stay strict.
  • Custom trust store: sshx --known-hosts=/path/to/known_hosts or SSH_KNOWN_HOSTS=/path/to/known_hosts.
  • Legacy insecure mode (last resort): sshx --insecure-hostkey ... or SSH_INSECURE_HOST_KEY=1. This re-enables the previous InsecureIgnoreHostKey behavior and should only be used in controlled environments.

If the host key ever changes, sshx clearly explains how to remove the old entry before re-connecting, protecting you from potential man-in-the-middle attacks.

Password Key Names
  • master: Default sudo password key name, used for sudo commands
  • root: Password for root user
  • Custom keys: You can use any key name, e.g., server-A, server-B, prod-db, etc.
Best Practices for Multi-Server Password Management

If you manage multiple servers with the same username but different passwords, use this strategy:

# Scenario: Manage 3 servers, all with root user but different passwords

# 1. Save password for each server (use meaningful key names)
sshx --password-set=prod-web      # Production web server
sshx --password-set=prod-db       # Production database server
sshx --password-set=dev-server    # Development server

# 2. Execute commands using -pk parameter to specify password key
sshx -h=192.168.1.10 -u=root -pk=prod-web "sudo systemctl status nginx"
sshx -h=192.168.1.20 -u=root -pk=prod-db "sudo systemctl status mysql"
sshx -h=192.168.1.30 -u=root -pk=dev-server "sudo docker ps"

# 3. You can also use aliases to simplify commands (add to ~/.zshrc or ~/.bashrc)
alias ssh-prod-web='sshx -h=192.168.1.10 -u=root -pk=prod-web'
alias ssh-prod-db='sshx -h=192.168.1.20 -u=root -pk=prod-db'
alias ssh-dev='sshx -h=192.168.1.30 -u=root -pk=dev-server'

# Then use simply:
ssh-prod-web "sudo systemctl restart nginx"
ssh-prod-db "sudo systemctl restart mysql"
ssh-dev "sudo docker-compose up -d"
Sudo Key Environment Variables

You can customize the sudo password key name via environment variable (but using -pk parameter is more flexible):

# Use environment variable (can only specify one at a time, needs constant modification)
export SSH_SUDO_KEY=my-sudo-password
sshx --password-set=my-sudo-password
sshx -h=192.168.1.100 "sudo ls -la /root"

# Recommended: Use -pk parameter, more flexible, no need to modify environment variables
sshx -h=192.168.1.100 -pk=server-A "sudo ls -la /root"
sshx -h=192.168.1.101 -pk=server-B "sudo ls -la /root"
Security Notes
  • โœ… Passwords are stored using OS-native encryption
  • โœ… Passwords are never stored in plaintext
  • โœ… Each host+user combination has a separate password entry
  • โœ… Password input is hidden during entry
  • โš ๏ธ Requires OS credential manager to be available
  • โš ๏ธ On Linux, requires Secret Service daemon running (usually automatic with desktop environments)
Connection Environment Variables

You can use environment variables to avoid typing credentials repeatedly:

# Set in .env file or export in shell
export SSH_HOST=192.168.1.100
export SSH_USER=root
export SSH_PORT=22
export SUDO_PASSWORD=your_sudo_password

# Then run commands without flags
./bin/sshx "uptime"
SSH Authentication Preferences
  • sshx now prioritizes SSH keys and automatically falls back to password authentication when the server rejects your key (for example when a host only allows passwords). As long as a password is available, the client will transparently retry with a password-only session.
  • Use --no-key (alias --password-only) to disable key authentication for a single command. You can re-enable it by supplying --key=<path> again.
  • Set SSH_DISABLE_KEY=true in your environment to permanently disable key authentication (useful on hosts that never accept keys). This override is respected even if a default key path exists in ~/.sshmcp/settings.json.
  • When key auth is enabled and no explicit path is provided, sshx still auto-loads ~/.ssh/id_rsa (or the path specified in settings) before falling back to passwords.
Log Level Configuration

You can control the logging verbosity using the SSHX_LOG_LEVEL environment variable:

# Set log level to DEBUG (shows detailed debugging information, including MCP requests/responses)
export SSHX_LOG_LEVEL=debug

# Set log level to INFO (default)
export SSHX_LOG_LEVEL=info

# Set log level to WARNING
export SSHX_LOG_LEVEL=warning

# Set log level to ERROR
export SSHX_LOG_LEVEL=error

Debug Logging in MCP Mode:

In MCP stdio mode, to avoid interfering with JSON-RPC communication, logs are written to a file instead of stdout. There are two ways to enable DEBUG level:

Method 1: Using --debug flag (Recommended)

# Start MCP server with --debug flag
sshx mcp-stdio --debug

# Log file location: ~/.sshmcp/sshx.log
# You can monitor logs in real-time
tail -f ~/.sshmcp/sshx.log

Method 2: Using environment variable

# Set environment variable to enable debug logging
export SSHX_LOG_LEVEL=debug
sshx mcp-stdio

# Log file location: ~/.sshmcp/sshx.log
# You can monitor logs in real-time
tail -f ~/.sshmcp/sshx.log

Note: The --debug flag takes precedence over the environment variable.

Debug level logs include:

  • All MCP requests received (JSON format)
  • All MCP responses sent (JSON format)
  • Detailed parameters and results of tool calls
  • Detailed SSH/SFTP operation processes
Example Workflow
# 1. Save sudo password (interactive input)
sshx --password-set=master
# Enter password for key 'master': ******

# 2. Verify it's saved
sshx --password-check=master
# โœ“ Password exists for key: master

# 3. Use for SSH commands (sudo automatically uses stored password)
sshx -h=192.168.1.100 -u=root "sudo systemctl status docker"
sshx -h=192.168.1.100 -u=root "sudo df -h"

# 4. Use for SFTP operations
sshx -h=192.168.1.100 -u=root --upload=local.txt --to=/tmp/remote.txt
sshx -h=192.168.1.100 -u=root --download=/etc/hosts --to=./hosts.txt

# 5. List all saved password keys
sshx --password-list
# Common keys:
#   โœ“ master (exists)
#     root (not set)

# 6. When done, optionally delete the password
sshx --password-delete=master
# โœ“ Password deleted from system keyring

Troubleshooting

"sshx: command not found"

Solution:

  • Ensure /usr/local/bin (or your installation directory) is in your PATH
  • Restart your terminal after installation
  • Or run with full path: /usr/local/bin/sshx
macOS Security Warning

macOS may block the binary on first run:

sudo xattr -rd com.apple.quarantine /usr/local/bin/sshx

Or go to System Preferences โ†’ Security & Privacy โ†’ Click "Allow Anyway"

Windows SmartScreen Warning

Click "More info" and then "Run anyway" if Windows Defender SmartScreen shows a warning.

Permission Denied
# Make sure the binary has execute permissions
sudo chmod +x /usr/local/bin/sshx

Development

# Run tests
go test ./...

# Format code
gofmt -w .

# Build for all platforms
make build-all

# Run linter
make lint

The lint target requires golangci-lint v2.6.1 or newer. Install it with go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.6.1.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation โ€ข Issues โ€ข Discussions โ€ข Releases

Made with โค๏ธ by talkincode

Directories ยถ

Path Synopsis
cmd
sshx command
internal
app
sshclient
pkg
errutil
logger

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.