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

1. Clone the repository:

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

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Install globally (optional):

   npm install -g .

Configuration

Claude Desktop Configuration

1. Open Claude Desktop
2. Go to Settings > Developer (or press Ctrl+Shift+D)
3. Edit the MCP configuration
4. 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

1. Connect to your server:

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

2. Check server status:

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

3. Upload a website file:

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

4. List website files:

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

5. Download a backup:

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

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

1. Edit source files in src/
2. Rebuild: npm run build
3. Test your changes
4. 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