mahathirmuh/mcp-ssh-server

MCP SSH Server

🚀 Overview

MCP SSH Server is a powerful Model Context Protocol (MCP) server that enables seamless SSH operations, file transfers, and remote server management. This server provides comprehensive SSH functionality including secure connections, file operations, interactive shell sessions, credential management, and Docker deployment capabilities.

✨ Features

• 🔐 Secure SSH Connections: Support for both password and SSH key authentication
• 📁 File Operations: Copy files between local and remote servers with directory creation
• 💻 Interactive Shell Sessions: Full terminal emulation with PTY support
• 🔑 Credential Management: Save and reuse SSH credentials securely
• 🐳 Docker Integration: Deploy and manage Docker containers remotely
• 📂 Working Directory Context: Maintain working directory state per connection
• 🔍 File System Operations: List files, get file info, and navigate directories
• ⚡ Connection Pooling: Efficient connection management and reuse

📋 Prerequisites

• Node.js 18+
• TypeScript 5.3+
• SSH access to target servers
• Claude Desktop or compatible MCP client

🛠️ Installation

1. Clone the repository:

   git clone <repository-url>
   cd mcp-ssh-server
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Configure Claude Desktop:

   Add to your Claude Desktop configuration file:

   Windows: %APPDATA%/Claude/claude_desktop_config.json

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

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

🎯 Available Tools

Connection Management

• ssh_connect - Establish SSH connection
• ssh_disconnect - Close SSH connection
• ssh_connect_with_credential - Connect using saved credentials

Command Execution

• ssh_execute - Execute commands on remote server
• ssh_start_interactive_shell - Start interactive shell session
• ssh_send_input - Send input to interactive shell
• ssh_read_output - Read output from interactive shell
• ssh_close_interactive_shell - Close interactive shell session

File Operations

• ssh_copy_file - Copy files between servers
• ssh_list_files - List directory contents
• ssh_file_info - Get file information

Credential Management

• ssh_save_credential - Save SSH credentials
• ssh_list_credentials - List saved credentials
• ssh_delete_credential - Delete saved credentials

Working Directory

• ssh_set_working_directory - Set current working directory
• ssh_get_working_directory - Get current working directory

Docker Operations

• ssh_docker_deploy - Deploy Docker containers
• ssh_docker_status - Check Docker container status

📖 Usage Examples

Basic SSH Connection

{
  "tool": "ssh_connect",
  "arguments": {
    "host": "192.168.1.100",
    "username": "user",
    "password": "password",
    "connectionId": "server1"
  }
}

SSH Key Authentication

{
  "tool": "ssh_connect",
  "arguments": {
    "host": "192.168.1.100",
    "username": "user",
    "privateKeyPath": "/path/to/private/key",
    "connectionId": "server1"
  }
}

File Transfer (Local to Remote)

{
  "tool": "ssh_copy_file",
  "arguments": {
    "sourceConnectionId": "local",
    "sourcePath": "/local/file.txt",
    "targetConnectionId": "server1",
    "targetPath": "/remote/file.txt"
  }
}

Execute Command

{
  "tool": "ssh_execute",
  "arguments": {
    "connectionId": "server1",
    "command": "ls -la /home/user"
  }
}

Docker Deployment

{
  "tool": "ssh_docker_deploy",
  "arguments": {
    "connectionId": "server1",
    "workingDirectory": "/app",
    "deploymentType": "compose"
  }
}

Save Credentials

{
  "tool": "ssh_save_credential",
  "arguments": {
    "credentialId": "my-server",
    "host": "192.168.1.100",
    "username": "user",
    "privateKeyPath": "/path/to/key"
  }
}

🔧 Development

# Development mode
npm run dev

# Type checking
npm run type-check

# Build
npm run build

# Start production
npm start

🔒 Security Considerations

• Store private keys securely with appropriate file permissions (600)
• Use SSH key authentication instead of passwords when possible
• Consider using SSH agent forwarding for additional security
• The server maintains connection pools - ensure proper cleanup on shutdown

🐛 Troubleshooting

Claude Desktop Integration Issues:

1. Verify the absolute path in claude_desktop_config.json is correct
2. Ensure the server was built successfully (npm run build)
3. Check that dist/index.js exists in your project directory
4. Restart Claude Desktop completely

SSH Connection Failures:

1. Verify SSH server is accessible from your machine
2. Test SSH connection manually: ssh username@hostname
3. Check SSH key permissions: chmod 600 ~/.ssh/id_rsa
4. Ensure SSH key is in the correct format (OpenSSH)

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.