Cross-platform MCP server for SSH connections with comprehensive remote server management tools
npm install @zibdie/ssh-mcp-server


A cross-platform Model Context Protocol (MCP) server that provides SSH connectivity tools. This server enables AI assistants to securely connect to and execute commands on remote servers via SSH.
- Cross-platform compatibility: Works on Windows, macOS, and Linux
- Multiple authentication methods: Username/password and SSH key authentication
- IPv4 and IPv6 support: Connect to servers using either IP version
- Multiple connections: Manage multiple SSH connections simultaneously
- Comprehensive file operations: Upload, download, and list files via SFTP
- Script execution: Run bash, python, and other scripts remotely
- Secure: Uses the robust ssh2 library for secure connections
- MCP compatible: Works with Claude CLI, Claude Desktop, and other MCP clients
1. Add to Claude CLI with one command:
``bash`
claude mcp add ssh-mcp-server npx '@zibdie/ssh-mcp-server@latest'
Windows Note: If you encounter MCP server startup issues on Windows, ensure you're using a supported terminal (Windows Terminal, PowerShell, or Git Bash) and that the Claude CLI has proper stdin support.
2. Restart Claude CLI
3. Test the connection:
``
"Connect to my server at example.com with username myuser"
#### For Claude CLI
1. Install globally:
`bash`
npm install -g @zibdie/ssh-mcp-server
2. Add to configuration:
macOS/Linux: Edit ~/.config/claude/claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json
Windows: Edit
`json`
{
"mcpServers": {
"ssh-mcp-server": {
"command": "ssh-mcp-server"
}
}
}
#### For Claude Desktop
1. Install globally:
`bash`
npm install -g @zibdie/ssh-mcp-server
2. Add to configuration:
macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json
Windows: Edit
`json`
{
"mcpServers": {
"ssh-mcp-server": {
"command": "ssh-mcp-server"
}
}
}
Here's an example of the SSH MCP server in action, showing file upload capabilities:
_Example: Uploading and managing files on remote servers through Claude using the SSH MCP server_
Connect to an SSH server using password or SSH key authentication.
Parameters:
- host (required): SSH server hostname or IP address (IPv4 or IPv6)port
- (optional): SSH server port (default: 22)username
- (required): Username for SSH authenticationpassword
- (optional): Password for authenticationprivateKey
- (optional): Path to private SSH key filepassphrase
- (optional): Passphrase for encrypted private keyconnectionId
- (optional): Unique identifier for this connection (default: "default")
Execute a command on an established SSH connection.
Parameters:
- command (required): Command to execute on the remote serverconnectionId
- (optional): Connection ID to use (default: "default")timeout
- (optional): Command timeout in milliseconds (default: 30000)
Disconnect from an SSH server.
Parameters:
- connectionId (optional): Connection ID to disconnect (default: "default")
List all active SSH connections.
Upload a file to the remote server via SFTP.
Parameters:
- localPath (required): Local file path to uploadremotePath
- (required): Remote destination pathconnectionId
- (optional): Connection ID to use (default: "default")createDirs
- (optional): Create remote directories if they don't exist (default: true)
Download a file from the remote server via SFTP.
Parameters:
- remotePath (required): Remote file path to downloadlocalPath
- (required): Local destination pathconnectionId
- (optional): Connection ID to use (default: "default")createDirs
- (optional): Create local directories if they don't exist (default: true)
List files and directories on the remote server.
Parameters:
- remotePath (optional): Remote directory path to list (default: ".")connectionId
- (optional): Connection ID to use (default: "default")detailed
- (optional): Show detailed file information (default: false)
User prompt: "Connect to my server at 192.168.1.100 with username admin and password mypass123"
``
ssh_connect with host="192.168.1.100", username="admin", password="mypass123"
User prompt: "SSH into my development server using my private key"
``
ssh_connect with host="dev.example.com", username="developer", privateKey="~/.ssh/id_rsa"
User prompt: "Connect to my IPv6 server with SSH key authentication"
``
ssh_connect with host="2001:db8::1", username="user", privateKey="/home/user/.ssh/dev_key", passphrase="keypassword"
User prompt: "Check the disk space on my server"
``
ssh_execute with command="df -h"
User prompt: "Show me what processes are running"
``
ssh_execute with command="ps aux | head -20"
User prompt: "Run a system update on my Ubuntu server"
``
ssh_execute_script with script="""
sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y
echo "System update completed"
""", interpreter="bash"
User prompt: "Copy the hello.zip file from my server's desktop to my desktop"
``
ssh_download_file with remotePath="/home/user/Desktop/hello.zip", localPath="~/Desktop/hello.zip"
User prompt: "Upload my config.json file to the server's /etc/myapp/ directory"
``
ssh_upload_file with localPath="./config.json", remotePath="/etc/myapp/config.json"
User prompt: "Send my backup script to the server and run it"
``
ssh_upload_and_execute with script="""
#!/bin/bash
mkdir -p /backup/$(date +%Y%m%d)
tar -czf /backup/$(date +%Y%m%d)/data_backup.tar.gz /var/www/html
echo "Backup completed successfully"
""", filename="backup.sh", interpreter="bash"
User prompt: "Show me what's in the /var/log directory with file sizes"
``
ssh_list_files with remotePath="/var/log", detailed=true
User prompt: "Connect to both my production and staging servers"
``
ssh_connect with host="prod.example.com", username="admin", privateKey="~/.ssh/prod_key", connectionId="production"
ssh_connect with host="staging.example.com", username="admin", privateKey="~/.ssh/staging_key", connectionId="staging"
User prompt: "Check uptime on both servers"
``
ssh_execute with command="uptime", connectionId="production"
ssh_execute with command="uptime", connectionId="staging"
User prompt: "Deploy my app to staging server"
``
ssh_upload_file with localPath="./myapp.tar.gz", remotePath="/tmp/myapp.tar.gz", connectionId="staging"
ssh_execute_script with script="""
cd /var/www
sudo tar -xzf /tmp/myapp.tar.gz
sudo systemctl restart nginx
sudo systemctl restart myapp
echo "Deployment completed"
""", connectionId="staging", interpreter="bash"
User prompt: "Run a Python script to analyze server performance"
`
ssh_execute_script with script="""
import psutil
import json
report = {
'cpu_usage': cpu_percent,
'memory_usage': memory.percent,
'disk_usage': (disk.used / disk.total) * 100,
'available_memory_gb': memory.available / (1024**3)
}
print(json.dumps(report, indent=2))
""", interpreter="python3"
`
User prompt: "Monitor my application logs in real-time"
``
ssh_execute with command="tail -f /var/log/myapp/application.log", timeout=60000
User prompt: "Backup my database and download it"
`
ssh_execute_script with script="""
timestamp=$(date +%Y%m%d_%H%M%S)
mysqldump -u dbuser -p'dbpass' mydatabase > /tmp/backup_$timestamp.sql
gzip /tmp/backup_$timestamp.sql
echo "Backup created: /tmp/backup_$timestamp.sql.gz"
""", interpreter="bash"
Security Considerations
- This tool provides direct SSH access to remote servers
- Always use strong authentication (prefer SSH keys over passwords)
- Be cautious when executing commands with elevated privileges
- Ensure proper network security and access controls
- Private keys and passwords are handled securely in memory
- Never commit credentials to version control
Requirements
- Node.js 18 or higher
- Network access to target SSH servers
- Valid SSH credentials for target servers
Troubleshooting
$3
1. "Command not found" after global install
`bash
# Ensure npm global bin is in your PATH
npm config get prefix
export PATH="$(npm config get prefix)/bin:$PATH"
`2. MCP server not appearing in Claude
- Verify configuration file path and JSON syntax
- Restart Claude CLI/Desktop after configuration changes
- Check Claude logs for connection errors
3. SSH connection failures
- Verify network connectivity to target server
- Ensure SSH service is running on target server
- Check firewall settings and port accessibility
- Validate SSH credentials and key permissions
4. Permission errors
- Ensure SSH keys have correct permissions (600)
- Verify user has necessary privileges on target server
Development
$3
1. Clone the repository:
`bash
git clone https://github.com/zibdie/SSH-MCP-Server.git
cd SSH-MCP-Server
`2. Install dependencies:
`bash
npm install
`3. Run in development mode:
`bash
npm run dev
`4. Test with MCP Inspector:
`bash
npx @modelcontextprotocol/inspector node index.js
``For detailed API documentation of all available tools and their parameters, see the Examples section above.
MIT - see LICENSE file for details
Nour Zibdie (https://nour.zibdie.com)
https://github.com/zibdie/SSH-MCP-Server