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.

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

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

🤝 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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

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.

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

Claude Dev Server
arben-adm
-
security
A
license
-
quality
The 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.
Last updated -
2
Python
MIT License
Adamik MCP Serverofficial
AdamikHQ
A
security
A
license
A
quality
Enables 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 -
12
1
2
TypeScript
MIT License
MCP Server for FTP Access
alxspiker
A
security
A
license
A
quality
Enables 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 -
6
8
JavaScript
MIT License
Desktop Commander MCP
MrGNSS
A
security
A
license
A
quality
A 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 -
19
23,971
4
MIT License

View all related MCP servers