Hermes Phone Agent

Hermes Agent with MCP servers for Android/iOS phone flashing, unlocking, and management

License: MIT Node.js

What is this?

Hermes Phone Agent extends Hermes Agent with Model Context Protocol (MCP) servers for controlling Android and iOS devices. It provides AI-powered phone management, flashing, unlocking, and automation.

Features

Android Support

• ADB: Full device control (shell, screenshots, input, file transfer)
• Fastboot: Flash partitions, unlock bootloader, reboot modes
• Heimdall: Samsung-specific flashing and PIT extraction
• App Management: Install, uninstall, list packages
• Screen Control: Screenshots, tap, swipe, text input, key events
• System Info: Battery, storage, logs, device properties

iOS Support

• libimobiledevice: Device info, app management, screenshots
• SSH/SFTP: Full access to jailbroken devices
• AFC: Apple File Conduit for file system access
• Backup/Restore: Full device backups
• Jailbreak Tools: checkra1n, palera1n instructions and status

Integration

• MCP Protocol: Works with Claude, Codex, Cursor, and any MCP client
• Hermes Agent: Telegram, Discord, Slack, WhatsApp, Signal gateway
• Windows Desktop: Native Windows support with one-click installer

Quick Start

Windows (Recommended)

1. Download the latest release from Releases
2. Run install.ps1 in PowerShell
3. Launch from desktop shortcut or Start Menu

Manual Install

# Clone the repository
git clone https://github.com/petrobumaga/hermes-phone-agent.git
cd hermes-phone-agent

# Install dependencies
npm install

# Start the agent
npm start

MCP-Only Mode

If you just want the MCP servers without Hermes Agent:

# Android MCP server only
npm run android-mcp

# iOS MCP server only
npm run ios-mcp

Configuration

Configuration file: ~/.hermes-phone-agent/config.yaml

android:
  enabled: true
  adbPath: auto        # Auto-detect or path to adb
  fastbootPath: auto
  heimdallPath: auto

ios:
  enabled: true
  sshUser: root
  sshPassword: alpine  # CHANGE THIS!
  sshPort: 22

hermes:
  enabled: true
  configPath: ~/.hermes/config.yaml

Available Tools

Android Tools (28 tools)

Tool	Description
android_list_devices	List connected devices
android_device_info	Get device properties
android_shell	Execute shell commands
android_screenshot	Capture screen
android_tap	Tap at coordinates
android_swipe	Swipe gesture
android_input_text	Type text
android_press_key	Press key (HOME, BACK, POWER, etc.)
android_list_packages	List installed apps
android_install_apk	Install APK
android_uninstall_app	Uninstall app
android_push_file	Push file to device
android_pull_file	Pull file from device
android_logcat	Get system logs
android_battery	Battery status
android_storage	Storage info
android_reboot	Reboot device
fastboot_devices	List fastboot devices
fastboot_flash	Flash partition
fastboot_unlock	Unlock bootloader
fastboot_reboot	Reboot from fastboot
fastboot_getvar	Get fastboot variable
heimdall_detect	Detect Samsung device
heimdall_flash	Flash Samsung partition
heimdall_download_pit	Download PIT table

iOS Tools (18 tools)

Tool	Description
ios_list_devices	List connected devices
ios_device_info	Get device info
ios_list_apps	List installed apps
ios_install_ipa	Install IPA
ios_uninstall_app	Uninstall app
ios_screenshot	Take screenshot
ios_syslog	Get system logs
ios_backup	Backup device
ios_ssh_command	Execute SSH command
ios_ssh_pull	Pull file via SSH
ios_ssh_push	Push file via SSH
ios_mount_afc	Mount AFC filesystem
ios_detect_jailbreak	Check jailbreak status
ios_checkra1n_info	checkra1n info
ios_palera1n_info	palera1n info
ios_dfu_instructions	DFU mode instructions
ios_reboot	Reboot device
ios_shutdown	Shutdown device

Use Cases

• Phone Repair: Diagnose and fix bootloops, soft bricks
• Flashing: Install custom ROMs, stock firmware
• Unlocking: Bootloader unlock, FRP bypass
• Jailbreaking: iPhone jailbreak with checkra1n/palera1n
• Automation: Automated testing, UI automation
• Data Recovery: Backup and restore, file extraction
• Security Research: Device analysis, forensic examination

Prerequisites

Android

• Android SDK Platform Tools (ADB, Fastboot)
• USB Debugging enabled on device
• (Optional) Heimdall for Samsung devices

iOS

• libimobiledevice utilities
• (For jailbroken) OpenSSH installed on device
• USB or WiFi connection

Development

# Install dev dependencies
npm install

# Run Android MCP server
npm run android-mcp

# Run iOS MCP server
npm run ios-mcp

# Start all services
npm start

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Hermes Agent by Nous Research
• MCP Protocol by Anthropic
• libimobiledevice for iOS support
• Android SDK for Android support
• Heimdall for Samsung flashing

Disclaimer

This tool is for educational and authorized testing purposes only. Always ensure you have proper authorization before modifying device software. The authors are not responsible for any damage caused by misuse of this software.