README - SSH-MCP by mixelpixx

MCP SSH Server

A Model Context Protocol (MCP) server that provides SSH access to remote servers, allowing AI tools like Claude Desktop or VS Code to securely connect to your VPS for website management.

Features

SSH connection management with password or key-based authentication
Remote command execution with timeout handling
File upload and download via SFTP
Directory listing
Secure connection handling
Compatible with Claude Desktop, VS Code, and other MCP-compatible clients

Prerequisites

Node.js 18 or higher
npm or yarn
Compatible with Windows, macOS, and Linux

Installation

Clone the repository:

git clone https://github.com/yourusername/mcp-ssh-server.git
cd mcp-ssh-server

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Install globally (optional):
```
npm install -g .
```

Configuration

Claude Desktop Configuration

Open Claude Desktop
Go to Settings > Developer (or press Ctrl+Shift+D)
Edit the MCP configuration
Add the following configuration:

{
  "mcpServers": {
    "ssh-server": {
      "command": "node",
      "args": ["/path/to/mcp-ssh-server/build/index.js"],
      "env": {
        "NODE_NO_WARNINGS": "1"
      }
    }
  }
}

Important: Replace /path/to/mcp-ssh-server/build/index.js with the absolute path to your built index.js file.

VS Code Configuration (if using MCP extension)

Create or edit .vscode/mcp.json in your workspace:

{
  "mcpServers": {
    "ssh-server": {
      "command": "node",
      "args": ["/path/to/mcp-ssh-server/build/index.js"]
    }
  }
}

Available Tools

ssh_connect

Establish an SSH connection to a remote server.

Parameters:

host (required) - Hostname or IP address
username (required) - SSH username
password (optional) - SSH password
privateKeyPath (optional) - Path to private key file
passphrase (optional) - Passphrase for private key
port (optional) - SSH port (default: 22)
connectionId (optional) - Unique identifier for this connection

Returns:

success - Boolean indicating success
connectionId - ID to use for subsequent commands
message - Connection status message

Example:

Connect to my server at example.com using username 'admin' and password authentication

ssh_exec

Execute a command on the remote server.

Parameters:

connectionId (required) - ID from ssh_connect
command (required) - Command to execute
cwd (optional) - Working directory
timeout (optional) - Command timeout in milliseconds (default: 60000)

Returns:

code - Exit code
signal - Signal that terminated the process (if any)
stdout - Standard output
stderr - Standard error

Example:

Run "ls -la /var/www/html" on the server

ssh_upload_file

Upload a file to the remote server.

Parameters:

connectionId (required) - ID from ssh_connect
localPath (required) - Local file path
remotePath (required) - Remote destination path

Returns:

success - Boolean indicating success
message - Upload status message

ssh_download_file

Download a file from the remote server.

Parameters:

connectionId (required) - ID from ssh_connect
remotePath (required) - Remote file path
localPath (required) - Local destination path

Returns:

success - Boolean indicating success
message - Download status message

ssh_list_files

List files in a directory on the remote server.

Parameters:

connectionId (required) - ID from ssh_connect
remotePath (required) - Directory path to list

Returns:

files - Array of file objects with properties:
- filename - File name
- isDirectory - Boolean indicating if it's a directory
- size - File size
- lastModified - Last modification time

ssh_disconnect

Close an SSH connection.

Parameters:

connectionId (required) - ID from ssh_connect

Returns:

success - Boolean indicating success
message - Disconnection status message

Usage Examples with Claude

Connect to your server:

Please connect to my VPS at example.com using username 'admin' and my SSH key at ~/.ssh/id_rsa

Check server status:

Run the command "systemctl status nginx" to check web server status

Upload a website file:

Upload my local file ~/websites/index.html to /var/www/html/index.html on the server

List website files:

Show me all files in the /var/www/html directory

Download a backup:

Download the file /var/backups/website-backup.tar.gz to my local Downloads folder

Disconnect when done:
```
Please disconnect from the SSH session
```

Planned Ubuntu Website Management Tools

The foundation is in place to add Ubuntu website management tools in src/ubuntu-website-tools.ts. Future enhancements will include:

Web server control (Apache/Nginx)
System package updates
Website deployment with backup
SSL certificate management (Let's Encrypt)
Server performance monitoring
Website backup functionality
WordPress management
Firewall (UFW) management

Security Notes

Store SSH private keys securely
Use key-based authentication when possible
Limit SSH access to specific IP addresses
Keep your server updated
Use strong passwords or passphrases
Consider setting up environment variables in a .env file for sensitive information

Troubleshooting

Server won't start

Check that Node.js is installed: node --version
Verify all dependencies are installed: npm install
Rebuild the project: npm run build

Connection issues

Verify SSH server is running on the target
Check firewall settings
Confirm credentials are correct
Test SSH connection manually first

Claude Desktop integration

Ensure the path in configuration is absolute
Restart Claude Desktop after configuration changes
Check Developer Console for error messages

Development

To modify or extend the server:

Edit source files in src/
Rebuild: npm run build
Test your changes
Restart Claude Desktop or VS Code to pick up changes

Running in Development Mode

For quick testing during development:

npm run dev

Contributing

Contributions for additional tools and features are welcome. Please feel free to submit pull requests or open issues for enhancements and bug fixes.

License

MIT License