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)
Python 3.8+
Claude Code CLI installed
npm (comes with Node.js)

🚀 Quick Start

Option A: Using Bash CLI (Recommended for Linux/Mac)

# Clone and install
git clone https://github.com/bvisible/mcp-ssh-manager.git
cd mcp-ssh-manager
npm install

# Install the Bash CLI
cd cli && ./install.sh

# Add servers using CLI
ssh-manager server add

# Test connection
ssh-manager server test production

# Quick SSH connection
ssh-manager ssh production

Option B: Using Python Configuration Tool

# Clone the repository
git clone https://github.com/bvisible/mcp-ssh-manager.git
cd mcp-ssh-manager

# Install dependencies
npm install
pip install -r tools/requirements.txt

# Configure servers
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:

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
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:

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

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

Never commit .env files - Always use .env.example as template
Use 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 servers
ssh_upload - Upload files to remote servers
ssh_download - Download files from remote servers
ssh_list_servers - List all configured SSH servers

Advanced Tools (v2.0)

ssh_sync - Bidirectional file synchronization with rsync
ssh_tail - Real-time log monitoring with follow mode
ssh_monitor - System metrics monitoring (CPU, RAM, disk, network)
ssh_history - View command execution history

Session Management

ssh_session_start - Start persistent SSH session
ssh_session_send - Send commands to active session
ssh_session_list - List active sessions
ssh_session_close - Close specific session

Server Groups

ssh_execute_group - Execute commands on server groups
ssh_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 statistics
ssh_tunnel_close - Close specific or all tunnels

Deployment & Security

ssh_deploy - Smart deployment with permission handling
ssh_execute_sudo - Execute commands with sudo privileges
ssh_alias - Manage server aliases

📚 Usage Examples

Using the Bash CLI

# Basic server management
ssh-manager server list
ssh-manager server add
ssh-manager ssh prod1

# File synchronization
ssh-manager sync push prod1 ./app /var/www/
ssh-manager sync pull prod1 /var/log/app.log ./

# SSH tunnels
ssh-manager tunnel create prod1 local 3307:localhost:3306
ssh-manager tunnel list

# Execute commands
ssh-manager exec prod1 "docker ps"

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.sh
```
Create 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

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github/workflows		.github/workflows
cli		cli
debug		debug
docs		docs
examples		examples
profiles		profiles
scripts		scripts
src		src
tests		tests
tools		tools
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.flake8		.flake8
.gitignore		.gitignore
.hooks-config.json		.hooks-config.json
.pre-commit-config.yaml		.pre-commit-config.yaml
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
package.json		package.json
pyproject.toml		pyproject.toml

License

bvisible/mcp-ssh-manager

Folders and files

Latest commit

History

Repository files navigation

MCP SSH Manager 🚀

🌟 Features

Core Features

New v2.0 Features 🆕

📋 Prerequisites

🚀 Quick Start

Option A: Using Bash CLI (Recommended for Linux/Mac)

Option B: Using Python Configuration Tool

4. Install to Claude Code

5. Start Using!

🛠️ Available MCP Tools

Core Tools

ssh_list_servers

ssh_execute

ssh_upload

ssh_download

Advanced Tools (v1.2+)

ssh_deploy 🚀

ssh_execute_sudo 🔐

ssh_alias 🏷️

ssh_command_alias 📝

ssh_hooks 🎣

ssh_profile 📚

🔧 Configuration

Profiles

Environment Variables

Server Management Tool

📁 Project Structure

🧪 Testing

Test Server Connection

Verify MCP Installation

Check Server Status in Claude Code

🔒 Security Best Practices

📚 Advanced Usage

Documentation

🐛 Troubleshooting

MCP Tools Not Available

Connection Failed

Permission Denied

🛠️ Available MCP Tools

Core Tools

Advanced Tools (v2.0)

Session Management

Server Groups

SSH Tunnels

Deployment & Security

📚 Usage Examples

Using the Bash CLI

Using in Claude Code

🤝 Contributing

Development Setup

Code Quality

📄 License

🙏 Acknowledgments

📧 Support

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 3

Languages

`ssh_list_servers`

`ssh_execute`

`ssh_upload`

`ssh_download`

`ssh_deploy` 🚀

`ssh_execute_sudo` 🔐

`ssh_alias` 🏷️

`ssh_command_alias` 📝

`ssh_hooks` 🎣

`ssh_profile` 📚

Packages