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.

Features

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

Installation & Setup

Quick Setup (Recommended)

Add to Claude CLI with one command:
```
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.
Restart Claude CLI

Test the connection:

"Connect to my server at example.com with username myuser"

Alternative: Manual Installation

For Claude CLI

Install globally:
```
npm install -g @zibdie/ssh-mcp-server
```
Add to configuration:

macOS/Linux: Edit ~/.config/claude/claude_desktop_config.json
Windows: Edit %APPDATA%\Claude\claude_desktop_config.json
```
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "ssh-mcp-server"
    }
  }
}
```

For Claude Desktop

Install globally:
```
npm install -g @zibdie/ssh-mcp-server
```
Add to configuration:

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: Edit %APPDATA%\Claude\claude_desktop_config.json
```
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "ssh-mcp-server"
    }
  }
}
```

Demo

Here's an example of the SSH MCP server in action, showing file upload capabilities:

SSH MCP Server Demo

Example: Uploading and managing files on remote servers through Claude using the SSH MCP server

Available Tools

`ssh_connect`

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 authentication
password (optional): Password for authentication
privateKey (optional): Path to private SSH key file
passphrase (optional): Passphrase for encrypted private key
connectionId (optional): Unique identifier for this connection (default: "default")

`ssh_execute`

Execute a command on an established SSH connection.

Parameters:

command (required): Command to execute on the remote server
connectionId (optional): Connection ID to use (default: "default")
timeout (optional): Command timeout in milliseconds (default: 30000)

`ssh_disconnect`

Disconnect from an SSH server.

Parameters:

connectionId (optional): Connection ID to disconnect (default: "default")

`ssh_list_connections`

List all active SSH connections.

`ssh_upload_file`

Upload a file to the remote server via SFTP.

Parameters:

localPath (required): Local file path to upload
remotePath (required): Remote destination path
connectionId (optional): Connection ID to use (default: "default")
createDirs (optional): Create remote directories if they don't exist (default: true)

`ssh_download_file`

Download a file from the remote server via SFTP.

Parameters:

remotePath (required): Remote file path to download
localPath (required): Local destination path
connectionId (optional): Connection ID to use (default: "default")
createDirs (optional): Create local directories if they don't exist (default: true)

`ssh_list_files`

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)

Examples

Basic Connection Examples

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"

Command Execution Examples

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"

File Transfer Examples

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

Multi-Server Management Examples

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"

Advanced Scripting Examples

User prompt: "Run a Python script to analyze server performance"

ssh_execute_script with script="""
import psutil
import json

# Get system info
cpu_percent = psutil.cpu_percent(interval=1)
memory = psutil.virtual_memory()
disk = psutil.disk_usage('/')

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"

# Then download the backup
ssh_download_file with remotePath="/tmp/backup_20241203_143022.sql.gz", localPath="./database_backup.sql.gz"

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

Common Issues

"Command not found" after global install

# Ensure npm global bin is in your PATH
npm config get prefix
export PATH="$(npm config get prefix)/bin:$PATH"

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
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
Permission errors
- Ensure SSH keys have correct permissions (600)
- Verify user has necessary privileges on target server

Development

Local Development

Clone the repository:

git clone https://github.com/zibdie/SSH-MCP-Server.git
cd SSH-MCP-Server

Install dependencies:
```
npm install
```
Run in development mode:
```
npm run dev
```

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node index.js

API Reference

For detailed API documentation of all available tools and their parameters, see the Examples section above.

License

MIT - see LICENSE file for details

Author

Nour Zibdie (https://nour.zibdie.com)

Repository

https://github.com/zibdie/SSH-MCP-Server

Support

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.

Features

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

Installation & Setup

Quick Setup (Recommended)

Add to Claude CLI with one command:
```
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.
Restart Claude CLI

Test the connection:

"Connect to my server at example.com with username myuser"

Alternative: Manual Installation

For Claude CLI

Install globally:
```
npm install -g @zibdie/ssh-mcp-server
```
Add to configuration:

macOS/Linux: Edit ~/.config/claude/claude_desktop_config.json
Windows: Edit %APPDATA%\Claude\claude_desktop_config.json
```
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "ssh-mcp-server"
    }
  }
}
```

For Claude Desktop

Install globally:
```
npm install -g @zibdie/ssh-mcp-server
```
Add to configuration:

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: Edit %APPDATA%\Claude\claude_desktop_config.json
```
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "ssh-mcp-server"
    }
  }
}
```

Demo

Here's an example of the SSH MCP server in action, showing file upload capabilities:

SSH MCP Server Demo

Example: Uploading and managing files on remote servers through Claude using the SSH MCP server

Available Tools

`ssh_connect`

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 authentication
password (optional): Password for authentication
privateKey (optional): Path to private SSH key file
passphrase (optional): Passphrase for encrypted private key
connectionId (optional): Unique identifier for this connection (default: "default")

`ssh_execute`

Execute a command on an established SSH connection.

Parameters:

command (required): Command to execute on the remote server
connectionId (optional): Connection ID to use (default: "default")
timeout (optional): Command timeout in milliseconds (default: 30000)

`ssh_disconnect`

Disconnect from an SSH server.

Parameters:

connectionId (optional): Connection ID to disconnect (default: "default")

`ssh_list_connections`

List all active SSH connections.

`ssh_upload_file`

Upload a file to the remote server via SFTP.

Parameters:

localPath (required): Local file path to upload
remotePath (required): Remote destination path
connectionId (optional): Connection ID to use (default: "default")
createDirs (optional): Create remote directories if they don't exist (default: true)

`ssh_download_file`

Download a file from the remote server via SFTP.

Parameters:

remotePath (required): Remote file path to download
localPath (required): Local destination path
connectionId (optional): Connection ID to use (default: "default")
createDirs (optional): Create local directories if they don't exist (default: true)

`ssh_list_files`

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)

Examples

Basic Connection Examples

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"

Command Execution Examples

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"

File Transfer Examples

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

Multi-Server Management Examples

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"

Advanced Scripting Examples

User prompt: "Run a Python script to analyze server performance"

ssh_execute_script with script="""
import psutil
import json

# Get system info
cpu_percent = psutil.cpu_percent(interval=1)
memory = psutil.virtual_memory()
disk = psutil.disk_usage('/')

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"

# Then download the backup
ssh_download_file with remotePath="/tmp/backup_20241203_143022.sql.gz", localPath="./database_backup.sql.gz"

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

Common Issues

"Command not found" after global install

# Ensure npm global bin is in your PATH
npm config get prefix
export PATH="$(npm config get prefix)/bin:$PATH"

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
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
Permission errors
- Ensure SSH keys have correct permissions (600)
- Verify user has necessary privileges on target server

Development

Local Development

Clone the repository:

git clone https://github.com/zibdie/SSH-MCP-Server.git
cd SSH-MCP-Server

Install dependencies:
```
npm install
```
Run in development mode:
```
npm run dev
```

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node index.js

API Reference

For detailed API documentation of all available tools and their parameters, see the Examples section above.

License

MIT - see LICENSE file for details

Author

Nour Zibdie (https://nour.zibdie.com)

Repository

https://github.com/zibdie/SSH-MCP-Server