The MCP SSH Manager enables Claude Code to seamlessly manage multiple SSH connections and perform remote operations through the Model Context Protocol (MCP).
Core Capabilities:
Execute commands on remote servers with optional working directory support and sudo privileges (with secure password masking)
Transfer files - upload to and download from remote systems
Deploy applications with automatic permission handling, backup creation, and service restart options
List configured SSH servers with their connection details
Management Features:
Server aliases - create shortcuts for frequently used servers
Command aliases - define shortcuts for common commands
Automation hooks - control project-specific workflows (list, enable, disable, status)
Configuration profiles - switch between different setups for various project types (default, frappe, docker, nodejs)
Provides Docker container management capabilities through SSH connections, including specialized command aliases and automation hooks for Docker operations
Offers ERPNext-specific SSH management features through specialized profiles, including custom command aliases and automation hooks tailored for ERPNext deployments
Provides Frappe framework-specific SSH management capabilities through dedicated profiles, including specialized command aliases and automation hooks for Frappe applications
Enables Node.js application management through SSH connections with specialized profiles, including custom command aliases and automation hooks for Node.js deployments
MCP SSH Manager 🚀
A powerful Model Context Protocol (MCP) server that enables Claude Code to manage multiple SSH connections seamlessly. Control remote servers, execute commands, and transfer files directly from Claude Code.
🌟 Features
Core Features
🔗 Multiple SSH Connections - Manage unlimited SSH servers from a single interface
🔐 Secure Authentication - Support for both password and SSH key authentication
📁 File Operations - Upload and download files between local and remote systems
⚡ Command Execution - Run commands on remote servers with working directory support
📂 Default Directories - Set default working directories per server for convenience
🎯 Easy Configuration - Simple
.env
file setup with guided configuration tool
New v2.0 Features 🆕
🚀 Bash CLI - Lightning-fast pure Bash CLI for server management
📊 Advanced Logging - Comprehensive logging system with levels and history
🔄 Rsync Integration - Bidirectional file sync with rsync support
💻 Persistent Sessions - Maintain shell context across multiple commands
👥 Server Groups - Execute commands on multiple servers simultaneously
🔧 SSH Tunnels - Local/remote port forwarding and SOCKS proxy support
📈 System Monitoring - Real-time monitoring of CPU, memory, disk, and network
🏷️ Server Aliases - Use short aliases instead of full server names
🚀 Smart Deployment - Automated file deployment with permission handling
🔑 Sudo Support - Execute commands with sudo privileges securely
📋 Prerequisites
Node.js (v18 or higher)
Claude Code CLI installed
npm (comes with Node.js)
Bash 4.0+ (for CLI)
rsync (for file synchronization)
sshpass (optional, for rsync with password authentication)
macOS:
brew install hudochenkov/sshpass/sshpass
Linux:
apt-get install sshpass
🚀 Quick Start
Server Configuration
The CLI provides an interactive wizard to configure servers:
Server name (e.g.,
production
,staging
)Host/IP address
Username
Port (default: 22)
Authentication method (SSH key recommended)
2. Install to Claude Code
3. Start Using!
In Claude Code, you can now:
With Default Directories:
If you set /var/www/html
as default for production, these commands are equivalent:
"Run 'ls' on production"
→ executes in/var/www/html
"Run 'ls' on production in /tmp"
→ executes in/tmp
(overrides default)
🛠️ Available MCP Tools
Core Tools
ssh_list_servers
Lists all configured SSH servers with their details.
ssh_execute
Execute commands on remote servers.
Parameters:
server
(name),command
,cwd
(optional working directory)Note: If no
cwd
is provided, uses the server's default directory if configured
ssh_upload
Upload files to remote servers.
Parameters:
server
,local_path
,remote_path
ssh_download
Download files from remote servers.
Parameters:
server
,remote_path
,local_path
Advanced Tools (v1.2+)
ssh_deploy
🚀
Deploy files with automatic permission and backup handling.
Parameters:
server
,files
(array),options
(owner, permissions, backup, restart)Automatically handles permission issues and creates backups
ssh_execute_sudo
🔐
Execute commands with sudo privileges.
Parameters:
server
,command
,password
(optional),cwd
(optional)Securely handles sudo password without exposing in logs
ssh_alias
🏷️
Manage server aliases for easier access.
Parameters:
action
(add/remove/list),alias
,server
Example: Create alias "prod" for "production" server
ssh_command_alias
📝
Manage command aliases for frequently used commands.
Parameters:
action
(add/remove/list/suggest),alias
,command
Aliases loaded from active profile
Example: Custom aliases for your project
ssh_hooks
🎣
Manage automation hooks for SSH operations.
Parameters:
action
(list/enable/disable/status),hook
Hooks loaded from active profile
Example: Project-specific validation and automation
ssh_profile
📚
Manage configuration profiles for different project types.
Parameters:
action
(list/switch/current),profile
Available profiles: default, frappe, docker, nodejs
Example: Switch between different project configurations
🔧 Configuration
Profiles
SSH Manager uses profiles to configure aliases and hooks for different project types:
Set active profile:
Environment variable:
export SSH_MANAGER_PROFILE=frappe
Configuration file: Create
.ssh-manager-profile
with profile nameDefault: Uses
default
profile if not specified
Available profiles:
default
- Basic SSH operationsfrappe
- Frappe/ERPNext specificdocker
- Docker container managementnodejs
- Node.js applicationsCreate custom profiles in
profiles/
directory
Environment Variables
Servers are configured in the .env
file with this pattern:
Server Management Tool
The Python management tool (tools/server_manager.py
) provides:
List servers - View all configured servers
Add server - Interactive server configuration
Test connection - Verify server connectivity
Remove server - Delete server configuration
Update Claude Code - Configure MCP in Claude Code
Install dependencies - Setup required packages
📁 Project Structure
🧪 Testing
Test Server Connection
Verify MCP Installation
Check Server Status in Claude Code
🔒 Security Best Practices
Never commit - Always use
.env.example
as templateUse SSH keys when possible - More secure than passwords
Limit server access - Use minimal required permissions
Rotate credentials - Update passwords and keys regularly
📚 Advanced Usage
Documentation
DEPLOYMENT_GUIDE.md - Deployment strategies and permission handling
ALIASES_AND_HOOKS.md - Command aliases and automation hooks
Real-world examples and best practices
🐛 Troubleshooting
MCP Tools Not Available
Ensure MCP is installed:
claude mcp list
Restart Claude Code after installation
Check server logs for errors
Connection Failed
Test connection:
python tools/test-connection.py [server_name]
Verify network connectivity
Check firewall rules
Ensure SSH service is running on remote server
Permission Denied
Verify username and password/key
Check SSH key permissions:
chmod 600 ~/.ssh/your_key
Ensure user has necessary permissions on remote server
🛠️ Available MCP Tools
Once installed in Claude Code, you'll have access to these powerful tools:
Core Tools
ssh_execute
- Execute commands on remote serversssh_upload
- Upload files to remote serversssh_download
- Download files from remote serversssh_list_servers
- List all configured SSH servers
Advanced Tools (v2.0)
ssh_sync
- Bidirectional file synchronization with rsyncssh_tail
- Real-time log monitoring with follow modessh_monitor
- System metrics monitoring (CPU, RAM, disk, network)ssh_history
- View command execution history
Session Management
ssh_session_start
- Start persistent SSH sessionssh_session_send
- Send commands to active sessionssh_session_list
- List active sessionsssh_session_close
- Close specific session
Server Groups
ssh_execute_group
- Execute commands on server groupsssh_group_manage
- Manage server groups (create, update, delete)
SSH Tunnels
ssh_tunnel_create
- Create SSH tunnels (local, remote, SOCKS)ssh_tunnel_list
- List active tunnels with statisticsssh_tunnel_close
- Close specific or all tunnels
Deployment & Security
ssh_deploy
- Smart deployment with permission handlingssh_execute_sudo
- Execute commands with sudo privilegesssh_alias
- Manage server aliases
📚 Usage Examples
Using the Bash CLI
Using in Claude Code
Once installed, simply ask Claude:
"List my SSH servers"
"Execute 'df -h' on production server"
"Upload this file to staging:/var/www/"
"Create an SSH tunnel to access remote MySQL"
"Monitor CPU usage on all servers"
"Start a persistent session on prod1"
🤝 Contributing
We welcome contributions! Please see CONTRIBUTING.md for details.
Development Setup
Fork the repository
Clone and install dependencies
Setup pre-commit hooks for code quality:
./scripts/setup-hooks.shCreate your feature branch
Make your changes (hooks will validate on commit)
Push to your branch
Open a Pull Request
Code Quality
This project uses automated quality checks:
ESLint for JavaScript linting
Black for Python formatting
Flake8 for Python linting
Prettier for code formatting
Pre-commit hooks for automated validation
Secret detection to prevent credential leaks
Run validation manually: ./scripts/validate.sh
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
Built for Claude Code
Uses the Model Context Protocol
SSH handling via node-ssh
Server management with Paramiko
📧 Support
For issues, questions, or suggestions:
Open an issue on GitHub Issues
Check existing issues before creating new ones
Made with ❤️ for the Claude Code community
Known Limitations
Command Timeout
The timeout parameter for SSH commands is advisory only
Due to SSH2 library limitations, commands may continue running on the server even after timeout
For critical timeout needs, use the system's
timeout
command directly in your command
SSH Sync (rsync)
Password authentication requires
sshpass
to be installedSSH key authentication is recommended for better security and reliability
Large file transfers may take time and appear to hang - be patient
Connection Management
Connections are pooled and reused for performance
If a connection becomes stale, it will be automatically reconnected on next use
Force reconnection by using the
ssh_connection_status
tool withreconnect
action
Support
For issues, feature requests, or contributions, please visit: https://github.com/bvisible/mcp-ssh-manager
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
Enables Claude to manage multiple SSH connections, execute remote commands, and transfer files across servers. Supports secure authentication, default directories, sudo operations, and deployment automation with profiles for different project types.
Related MCP Servers
- -securityAlicense-qualityThe Claude Dev Server enables direct interaction with the file system within a specified workspace, allowing users to perform file and directory operations and implement code artifacts in software development using natural language commands.
Adamik MCP Serverofficial
AsecurityAlicenseAqualityEnables read and write interactions with 60+ blockchain networks through Claude Desktop, providing a standardized multi-chain API for transaction management, account insights, staking, and token interactions.Last updated -1272MIT License- AsecurityAlicenseAqualityEnables Claude to interact with FTP servers through natural language commands, allowing users to list directories, download/upload files, create directories, and delete files/directories on FTP servers.Last updated -611MIT License
- AsecurityAlicenseAqualityA server that lets Claude desktop app execute terminal commands on your computer and edit files through Model Context Protocol, featuring command execution, process management, and advanced file operations.Last updated -1925,1814MIT License