# MCP SSH Server

<div align="center">
  <a href="README.md">🇺🇸 English</a> | <a href="README-id.md">🇮🇩 Bahasa Indonesia</a>
</div>

### 🚀 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:**
   ```bash
   git clone <repository-url>
   cd mcp-ssh-server
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Build the project:**
   ```bash
   npm run build
   ```

4. **Configure Claude Desktop:**
   
   Add to your Claude Desktop configuration file:
   
   **Windows:** `%APPDATA%/Claude/claude_desktop_config.json`
   ```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`
   ```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
```json
{
  "tool": "ssh_connect",
  "arguments": {
    "host": "192.168.1.100",
    "username": "user",
    "password": "password",
    "connectionId": "server1"
  }
}
```

#### SSH Key Authentication
```json
{
  "tool": "ssh_connect",
  "arguments": {
    "host": "192.168.1.100",
    "username": "user",
    "privateKeyPath": "/path/to/private/key",
    "connectionId": "server1"
  }
}
```

#### File Transfer (Local to Remote)
```json
{
  "tool": "ssh_copy_file",
  "arguments": {
    "sourceConnectionId": "local",
    "sourcePath": "/local/file.txt",
    "targetConnectionId": "server1",
    "targetPath": "/remote/file.txt"
  }
}
```

#### Execute Command
```json
{
  "tool": "ssh_execute",
  "arguments": {
    "connectionId": "server1",
    "command": "ls -la /home/user"
  }
}
```

#### Docker Deployment
```json
{
  "tool": "ssh_docker_deploy",
  "arguments": {
    "connectionId": "server1",
    "workingDirectory": "/app",
    "deploymentType": "compose"
  }
}
```

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

### 🔧 Development

```bash
# 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.

---

<div align="center">
  <p>Made with ❤️ for seamless SSH operations</p>
  <p><a href="README-id.md">🇮🇩 Baca dalam Bahasa Indonesia</a></p>
</div>