MCP Ssh Manager

🚀 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.

🚀 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)

✨ 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

📦 Installation

Prerequisites

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

💻 Usage Examples

Basic Usage

In Claude Code, you can manage SSH connections and perform operations easily. For example, to list all configured SSH servers:

"List all my SSH servers"

Advanced Usage

Automated File Deployment

# Use the ssh_deploy tool to deploy files with automatic permission and backup handling
python tools/server_manager.py ssh_deploy production ["file1.txt", "file2.txt"] --owner root --permissions 644 --backup --restart

Execute Commands with Sudo Privileges

# Use the ssh_execute_sudo tool to run commands with sudo privileges
python tools/server_manager.py ssh_execute_sudo production "apt update" --password your_sudo_password

📚 Documentation

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

Advanced Usage

• 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

🔧 Technical Details

This section could potentially cover more in - depth information about how the MCP SSH Manager interacts with the Model Context Protocol, the underlying algorithms for handling multiple SSH connections, and the security mechanisms implemented for authentication and command execution. However, the original README did not provide such detailed technical content.

📄 License

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

🤝 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

🙏 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