Content
# WinCommander
> **Mobile Brain → Windows Limbs**. Turn any Windows device into a remotely controllable MCP toolset.
> The Hermes in Termux on the mobile phone is the only AI Agent, and Windows only needs to execute without an API Key.
## Architecture
```
┌─────────────────────────────┐
│ Mobile (Termux + Hermes) │
│ The only AI Brain │
│ │
│ "Open the browser on Win and │
│ search for Python docs" │
│ │
│ Agent calls tools: │
│ mcp_win_browser_navigate │
│ mcp_win_input_type │
│ mcp_win_cli_run │
└──────────┬──────────────────┘
│ LAN / Tailscale
▼
┌─────────────────────────────┐
│ Windows (WinCommander) │
│ Brainless Executor │
│ │
│ ✅ CLI (CMD/PowerShell) │
│ ✅ GUI (UIA Desktop Automation) │
│ ✅ Browser (Playwright) │
│ ✅ Keyboard & Mouse (pyautogui) │
│ ✅ USB Device Management │
│ ✅ Screenshot / Clipboard │
│ ✅ File System │
│ ✅ Process Management │
│ │
│ No API Key · Fully Offline │
└─────────────────────────────┘
```
## Features (35+ Tools)
| Category | Tool | Description |
|------|------|------|
| **CLI** | `cli_run` | Execute CMD command |
| | `cli_powershell` | Execute PowerShell |
| **GUI** | `gui_snapshot` | Get desktop UI element tree |
| | `gui_click` | Click element |
| | `gui_double_click` | Double-click element |
| | `gui_type` | Input text to element |
| | `gui_press` | Send key |
| | `gui_focus` | Focus element |
| | `gui_invoke` | Trigger button |
| | `gui_window_list` | List all windows |
| | `gui_window_focus` | Bring window to front |
| | `gui_window_close` | Close window |
| **Input** | `input_click` | Mouse click at coordinates |
| | `input_double_click` | Mouse double-click |
| | `input_move` | Move mouse |
| | `input_drag` | Drag |
| | `input_type` | Keyboard input text |
| | `input_hotkey` | Hotkey (Ctrl+C, Win+R…) |
| | `input_scroll` | Scroll wheel |
| **Browser** | `browser_navigate` | Open webpage |
| | `browser_click` | Click element |
| | `browser_type` | Input text to box |
| | `browser_snapshot` | Get page text |
| | `browser_exec` | Execute JS |
| | `browser_scroll` | Scroll page |
| | `browser_close` | Close browser |
| **Screenshot** | `screen_screenshot` | Full screen/region screenshot |
| | `screen_size` | Screen resolution |
| **USB** | `usb_list` | List USB devices |
| | `usb_detailed` | USB detailed information |
| **System** | `system_info` | System information |
| | `system_processes` | Process list |
| | `system_kill` | Kill process |
| **File** | `file_list` | List directory |
| | `file_read` | Read file |
| | `file_write` | Write file |
| | `file_delete` | Delete file |
| | `file_exists` | Check existence |
| **Clipboard**| `clipboard_get` | Read clipboard |
| | `clipboard_set` | Write clipboard |
| **App** | `app_start` | Start app |
## Quick Start
### 1. Windows Deployment
```batch
git clone https://github.com/your-repo/win-commander.git
cd win-commander
setup_win.bat
```
The script automatically completes:
- Detection of Python 3.10+
- Creation of venv and installation of all dependencies
- Download of Playwright Chromium browser (~150MB)
- Generation of startup batch file
### 2. Start
```batch
start_WinCommander.bat # No whitelist restriction
start_WinCommander_safe_mode.bat # Restricted user directory
```
After startup, the terminal displays:
```
╔══════════════════════════════════════════════════╗
║ WinCommander — Windows Remote Control ║
╠══════════════════════════════════════════════════╣
║ LAN IP : 192.168.1.100 ║
║ Port : 9600 ║
║ MCP URL : http://192.168.1.100:9600/mcp ║
╠══════════════════════════════════════════════════╣
║ Termux configuration: ║
║ hermes config set mcp_servers.win.url ║
║ "http://192.168.1.100:9600/mcp" ║
╚══════════════════════════════════════════════════╝
```
### 3. Mobile (Termux) Configuration
```bash
# Method A: Automatic configuration (on Linux/Termux)
bash setup_termux.sh
# Method B: Manual configuration
hermes config set mcp_servers.win.url "http://192.168.1.100:9600/mcp"
# Restart Hermes
hermes gateway restart
```
### 4. Start Using
Directly chat with Hermes on the mobile phone:
```
"Look at what windows are on Windows"
"Use mcp_win_system_info to see system status"
"Open Chrome on Windows and search for Python documentation"
"Help me create a test.txt file on the Windows desktop"
```
All tools are prefixed with `mcp_win_`. Hermes will automatically discover and call.
## Security
| Mechanism | Description |
|------|------|
| **Whitelist** | `--whitelist` restricts file access directory |
| **SSRF Protection** | Browser prohibits access to localhost/private IP/cloud metadata |
| **Tailscale** | Use WireGuard encrypted tunnel when using across networks |
| **HMAC** | `--secret` optional authentication key |
## Optional Dependencies
| Library | Purpose | Impact of absence |
|---|---|---|
| `uiautomation` | GUI automation | `gui_*` tools unavailable |
| `pyautogui` | Keyboard & mouse simulation | `input_*` tools unavailable |
| `playwright` | Browser | `browser_*` tools unavailable |
| `pyperclip` | Clipboard | `clipboard_*` tools unavailable |
| `mss` + `Pillow` | Screenshot | `screen_*` falls back to pyautogui |
| `psutil` | System information | Memory/disk information missing |
## Relationship with Hermes-Desktop / remote-device-mcp
WinCommander absorbs the essence of these two projects:
- **Hermes-Desktop** provides Windows GUI automation (FlaUI.UIA3 → uiautomation) and browser automation (Playwright) tool design patterns
- **hermes-remote-device-mcp** provides MCP Server remote control architecture ideas, but fixes issues like missing HMAC authentication and shell injection
Differences:
| | Hermes-Desktop | remote-device-mcp | **WinCommander** |
|---|---|---|---|
| Platform | Windows only | Cross-platform | **Windows only** |
| AI Location | Local agent runtime | Remote Hermes | **Remote Hermes (mobile)** |
| API Key | Required | Not required | **Not required** |
| GUI Automation | FlaUI.UIA3 (C#) | ❌ | **uiautomation (Python)** |
| Browser | Playwright (implemented but not registered) | ❌ | **Playwright** |
| Keyboard & Mouse | Embedded UIA | ❌ | **Independent pyautogui tool** |
| USB | ❌ | ❌ | **✅** |
| Security | HMAC + Whitelist | HMAC fake implementation | **Real HMAC + SSRF + Whitelist** |
## License
MIT
