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

• 🔗 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
• 🔧 Connection Testing - Built-in tools to verify server connectivity
• 🚀 Smart Deployment - NEW! Automated file deployment with permission handling
• 🔑 Sudo Support - NEW! Execute commands with sudo privileges securely
• 🏷️ Server Aliases - NEW! Use short aliases instead of full server names

📋 Prerequisites

• Node.js (v16 or higher)
• Python 3.8+
• Claude Code CLI installed
• npm (comes with Node.js)

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/mcp-ssh-manager.git
cd mcp-ssh-manager

2. Install Dependencies

npm install
pip install -r tools/requirements.txt

3. Configure Your Servers

Run the interactive configuration tool:

python tools/server_manager.py

Choose option 2 to add a server. You'll be prompted for:

• Server name (e.g., production, staging)
• Host/IP address
• Username
• Port (default: 22)
• Authentication method (password or SSH key)

4. Install to Claude Code

# For personal use (current user only)
claude mcp add ssh-manager node /path/to/mcp-ssh-manager/src/index.js

# For team sharing (creates .mcp.json in project)
claude mcp add ssh-manager --scope project node /path/to/mcp-ssh-manager/src/index.js

# For all your projects
claude mcp add ssh-manager --scope user node /path/to/mcp-ssh-manager/src/index.js

5. Start Using!

In Claude Code, you can now:

"List all my SSH servers"
"Execute 'ls -la' on production server"  # Uses default directory if set
"Run 'docker ps' on staging"
"Upload config.json to production:/etc/app/config.json"
"Download logs from staging:/var/log/app.log"

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:

1. Set active profile:

   • Environment variable: export SSH_MANAGER_PROFILE=frappe
   • Configuration file: Create .ssh-manager-profile with profile name
   • Default: Uses default profile if not specified

2. Available profiles:

   • default - Basic SSH operations
   • frappe - Frappe/ERPNext specific
   • docker - Docker container management
   • nodejs - Node.js applications
   • Create custom profiles in profiles/ directory

Environment Variables

Servers are configured in the .env file with this pattern:

# Server configuration pattern
SSH_SERVER_[NAME]_HOST=hostname_or_ip
SSH_SERVER_[NAME]_USER=username
SSH_SERVER_[NAME]_PASSWORD=password  # For password auth
SSH_SERVER_[NAME]_KEYPATH=~/.ssh/key  # For SSH key auth
SSH_SERVER_[NAME]_PORT=22  # Optional, defaults to 22
SSH_SERVER_[NAME]_DEFAULT_DIR=/path/to/dir  # Optional, default working directory
SSH_SERVER_[NAME]_DESCRIPTION=Description  # Optional

# Example
SSH_SERVER_PRODUCTION_HOST=prod.example.com
SSH_SERVER_PRODUCTION_USER=admin
SSH_SERVER_PRODUCTION_PASSWORD=secure_password
SSH_SERVER_PRODUCTION_PORT=22
SSH_SERVER_PRODUCTION_DEFAULT_DIR=/var/www/html
SSH_SERVER_PRODUCTION_DESCRIPTION=Production Server
SSH_SERVER_PRODUCTION_SUDO_PASSWORD=secure_sudo_pass  # Optional, for automated deployments

Server Management Tool

The Python management tool (tools/server_manager.py) provides:

1. List servers - View all configured servers
2. Add server - Interactive server configuration
3. Test connection - Verify server connectivity
4. Remove server - Delete server configuration
5. Update Claude Code - Configure MCP in Claude Code
6. Install dependencies - Setup required packages

📁 Project Structure

mcp-ssh-manager/
├── src/
│   └── index.js           # Main MCP server implementation
├── tools/
│   ├── server_manager.py  # Interactive server management
│   ├── test-connection.py # Connection testing utility
│   └── requirements.txt   # Python dependencies
├── examples/
│   ├── .env.example       # Example configuration
│   └── claude-code-config.example.json
├── package.json           # Node.js dependencies
├── .env                   # Your server configurations (create from .env.example)
└── README.md             # This file

🧪 Testing

Test Server Connection

python tools/test-connection.py production

Verify MCP Installation

claude mcp list

Check Server Status in Claude Code

/mcp

🔒 Security Best Practices

1. Never commit .env files - Always use .env.example as template
2. Use SSH keys when possible - More secure than passwords
3. Limit server access - Use minimal required permissions
4. 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

1. Ensure MCP is installed: claude mcp list
2. Restart Claude Code after installation
3. Check server logs for errors

Connection Failed

1. Test connection: python tools/test-connection.py [server_name]
2. Verify network connectivity
3. Check firewall rules
4. Ensure SSH service is running on remote server

Permission Denied

1. Verify username and password/key
2. Check SSH key permissions: chmod 600 ~/.ssh/your_key
3. Ensure user has necessary permissions on remote server

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

1. Fork the repository
2. Clone and install dependencies
3. Setup pre-commit hooks for code quality:

   ./scripts/setup-hooks.sh
   

4. Create your feature branch
5. Make your changes (hooks will validate on commit)
6. Push to your branch
7. 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