Azdroid

Next-gen Android screen mirroring, desktop control, and Model Context Protocol (MCP) server for macOS and Windows over Wi-Fi & USB. Built with Flutter Desktop & scrcpy.

   
_{macOS: Universal Binary (31 MB) • Apple Silicon (M1/M2/M3/M4) & Intel Core • macOS 12.0+
Windows (Preview): portable ZIP (25 MB) • Windows 10/11 x64 • what works on each platform}

---

🚀 Why Azdroid?

Azdroid turns your Mac or Windows PC into the ultimate Android command center. Whether you are an Android developer debugging apps, a content creator recording mobile gameplay, or a power user seeking desktop control over your phone, Azdroid delivers:

• ⚡️ Low-Latency Native Decoding: Hardware H.264 encoding on the phone, decoded natively on the desktop (Apple VideoToolbox on macOS, Media Foundation on Windows) at up to 60 FPS, at the phone's own resolution.
• 📶 Dual Connection (Wi-Fi & USB): Subnet ARP auto-discovery, mDNS wireless debugging, 1-click USB-to-Wi-Fi switch, or instant plug-and-play USB cable mode.
• 🔋 Screen-Off Streaming: Keep the physical phone screen dark while you keep mirroring and controlling it, for privacy and less battery drain from the display.
• 🔒 100% Private & P2P: Zero cloud servers, zero analytics, and zero telemetry. All video, audio, and inputs remain strictly inside your local network.

---

📸 Visual Showcase

1. Subnet Discovery & Built-in Feature Catalog

Multi-Device Discovery Subnet auto-scan, connection badges, Wi-Fi/USB switch for dual-mode devices & 1-click mirroring.

Interactive Feature Showcase Categorized catalog with performance badges, highlights & pro tips.

2. Developer Inspection: Logcat & Intent Dispatcher

Device Logcat Console (Cmd+Shift+L) Live stream (batched every 100 ms), 5k ring buffer, regex/PID/tag filters, star bookmarks & recording to a file.

Deep Link & Intent Dispatcher (Cmd+Shift+D) Fire custom URI schemes, system actions, targeted packages & typed extras.

3. App Deployment & Two-Way File Management

1-Click APK Manager (Cmd+Shift+I) AAPT2 metadata inspection, permission grant flags, 1-click launch & clean uninstall.

Device File Explorer (Cmd+Shift+F) Two-way file browser with quick folder shortcuts & batch download.

4. Lossless Media Capture & Screen Recording

Hardware Screen Recording (Cmd+Shift+R) H.264 MP4 encoded by the phone's hardware encoder (up to 3 minutes), with a 3 s countdown HUD.

Interactive Area Crop (Cmd+Shift+S) PNG marquee crop with live pixel badge; copy, save, or both.

5. Remote Text Input

Remote Text Injection (Cmd+K)
_{Type or paste text for the phone; Vietnamese, CJK, and emoji arrive intact.}

---

🤖 Autonomous AI Agent Architecture & Workflow (MCP Server)

Connect Claude Desktop, Cursor, Antigravity, and Cline directly to your physical or emulated Android devices with zero UI overhead. For detailed step-by-step triage, see the Autonomous Workflow Guide and AI Agent Setup Guide.

⚡️ Executive Overview

The Azdroid MCP Server (azdroid-mcp) transforms your connected Android devices (physical hardware or emulators over Wi-Fi and USB) into an autonomous testing and automation environment for AI assistants (e.g., Claude Desktop, Cursor, Antigravity, Cline).

Operating over standard I/O (stdio) via JSON-RPC 2.0, the server provides 62 specialized tools. This empowers AI agents to see, touch, inspect, debug, and verify Android applications in a complete autonomous closed loop:

flowchart TD
    subgraph P1 ["Phase 1: Task Intake"]
        A["🎯 1. User Request\nHigh-level goal or bug report"]
    end

    subgraph P2 ["Phase 2: Perception & Action (Observe & Act)"]
        B["👀 2. Sensory Inspection\nXML Semantic Tree & Screenshot"]
        C["👆 3. Touch & Input\nHardware taps, typing & gestures"]
        B --> C
    end

    subgraph P3 ["Phase 3: Triage & Rectification (Diagnose & Repair)"]
        D["🚨 4. Error Interception\nCrash dump & logcat traces"]
        E["🛠️ 5. Source Code Fix\nRoot cause repair in IDE"]
        D --> E
    end

    subgraph P4 ["Phase 4: Closed-Loop Assurance (Verify & Deliver)"]
        F["🔁 6. Automated Re-verification\nCold restart & replay macro"]
        G["✅ 7. Final Delivery\nAudited report with proof"]
        F --> G
    end

    A ==> B
    C ==> D
    E ==> F
    F -.->|Regression Detected| D

    classDef stage fill:#1E293B,stroke:#475569,stroke-width:1.5px,color:#F8FAFC;
    class A,B,C,D,E,F,G stage;
    style A stroke:#3B82F6,stroke-width:2px
    style B stroke:#0EA5E9,stroke-width:2px
    style C stroke:#14B8A6,stroke-width:2px
    style D stroke:#EF4444,stroke-width:2px
    style E stroke:#F59E0B,stroke-width:2px
    style F stroke:#8B5CF6,stroke-width:2px
    style G stroke:#10B981,stroke-width:2px

Phase	Step	Purpose	Primary Azdroid MCP Tools
1	🎯 User Request	Delegating task or bug reproduction prompt	Client Prompt Context
2	👀 Sensory Inspection	Grounding UI structure with millimeter accuracy	android_get_ui_tree, android_take_screenshot
3	👆 Touch & Action	Injecting multi-touch, typing, and key events	android_tap, android_input_text, android_swipe
4	🚨 Error Interception	Capturing stack traces, ANRs, and log buffers	android_get_logcat (crashesOnly)
5	🛠️ Source Code Fix	Editing source files and resolving root causes	IDE File Tools / Compiler
6	🔁 Re-verification	Replaying user journey on physical device	android_launch_app, android_batch_actions
7	✅ Final Delivery	Delivering verified outcome with evidence	Final Audit Report

---

🏛️ High-Level Interaction Architecture

sequenceDiagram
    autonumber
    actor User as 👤 Engineer / QA
    participant AI as 🤖 AI Assistant (Claude / Cursor / Antigravity)
    participant MCP as ⚡️ Azdroid MCP Server (azdroid-mcp)
    participant Device as 📱 Android Device (Wi-Fi / USB)
    participant Desktop as 🖥️ Azdroid Desktop Viewport (macOS / Windows)

    User->>AI: 1. Dispatches high-level task / bug report
    Note over AI: 2. Formulates multi-step execution plan

    rect rgb(240, 248, 255)
        Note over AI,Device: Perception & Interaction Loop (Observe & Act)
        AI->>MCP: android_list_devices & android_get_current_app
        MCP->>Device: Low-level ADB inspection
        Device-->>MCP: Hardware state & foreground activity
        MCP-->>AI: Active device telemetry

        AI->>MCP: android_get_ui_tree & android_take_screenshot
        MCP->>Device: Dump accessibility hierarchy & screen frame
        Device-->>MCP: UI node coordinates & visual frame
        MCP-->>AI: Semantic UI Tree (XML) & PNG screenshot
        
        opt Real-time Mirroring Observation
            Device-->>Desktop: H.264 Video Stream (60 FPS, < 30ms latency)
            Desktop-->>User: Visual feedback of AI gestures & clicks in real time
        end

        AI->>MCP: android_tap / android_input_text / android_swipe
        MCP->>Device: Hardware input event injection
    end

    rect rgb(255, 245, 245)
        Note over AI,Device: Diagnostic Interception (Triage)
        AI->>MCP: android_get_logcat (crashesOnly, then by tag)
        Device-->>MCP: Crash stack trace & logcat buffer
        MCP-->>AI: Root cause evidence (NullPointer, ANR, 500 API)
    end

    rect rgb(245, 255, 245)
        Note over AI,User: Source Code Rectification & Verification (Fix & Verify)
        AI->>AI: Locates error in codebase, edits code, triggers build
        AI->>MCP: android_launch_app (Restarts updated application)
        AI->>MCP: android_batch_actions (Re-plays user flow)
        AI->>MCP: android_get_ui_tree (Verifies success dialog)
        MCP-->>AI: UI validated with zero crashes
    end

    AI-->>User: Delivers comprehensive completion report with evidence

---

⚡️ Complete Feature Catalog

Azdroid includes 14 built-in modules (plus a planned menu bar companion):

#	Feature	Highlights & Capabilities	Shortcut	Docs
01	Wireless Display & Low-Latency Streaming	Up to 60 FPS at native resolution, H.264 hardware decoding (VideoToolbox on macOS, Media Foundation on Windows), live FPS / bitrate / latency badges	Auto	Guide
02	Device Discovery & Wireless Pairing	Subnet ARP scan, 1-click USB-to-Wi-Fi, mDNS discovery for Android 11+ pairing	Auto / Toolbar	Guide
03	Remote Input & Gesture Control	Trackpad scrolling, two-finger pinch and rotate (trackpad or Alt + drag), right-click back, over the scrcpy control socket	Mouse / Trackpad	Guide
04	Keyboard & Text Injection	Desktop keyboard shortcuts and a text input modal; Vietnamese, CJK, and emoji are pasted intact	Cmd+K	Guide
05	Screen-Off Streaming	Turns the phone's display panel off while mirroring and control continue	Cmd+O	Guide
06	Device Logcat Console & Debugger	Live stream (batched every 100 ms), 5k ring buffer, regex/PID/tag filters, star bookmarks, recording to a file	Cmd+Shift+L	Guide
07	Deep Link & Intent Dispatcher	Test URI schemes, system actions (VIEW, SEND), packages & typed extras	Cmd+Shift+D	Guide
08	APK Sideload & Package Manager	AAPT2 package inspection, install flags (-r, -g, -t), launch & uninstall	Cmd+Shift+I	Guide
09	Two-Way File Explorer	Two-way file manager, quick folders (Downloads, DCIM, Docs) & download to the computer	Cmd+Shift+F	Guide
10	Viewport Drag & Drop Push	Drag any file or APK onto the mirroring window for instant push or sideload	Drag-and-drop	Guide
11	Bidirectional Clipboard Sync	Desktop clipboard ⇄ Android clipboard every 2 s, with loop prevention	Auto, or Cmd+Shift+C / V	Guide
12	Hardware MP4 Screen Recording	H.264 MP4 (8 Mbps, up to 3 minutes) encoded on the phone, 3 s countdown HUD, live timer	Cmd+Shift+R	Guide
13	Lossless Screenshots & Area Crop	Full PNG capture or interactive 8-handle marquee crop, to the clipboard, your Downloads folder, or both	Cmd+S / Shift+S	Guide
14	Model Context Protocol (MCP) AI Agent Server	Headless stdio MCP server exposing 38 tools for Claude Desktop, Cursor & Antigravity; the toolbar hub icon shows its setup, connected AI sessions, and live tool calls; the mirror shows when an AI controls the device	Stdio CLI / Hub icon	Guide
+	Menu Bar Companion (not yet available)	Status bar popover for quick window toggle and live telemetry (FPS & latency); designed, not yet wired into the app	Menu Bar	Guide

Shortcuts are shown with Cmd (macOS); use Ctrl on Windows. Most features are verified on macOS; the Windows preview has verified mirroring, logcat, bitrate presets, and the MCP server. Audio forwarding (Android 11+) is new and not yet verified in the app on either platform. Full matrix: Platform Support.

---

⌨️ Essential Keyboard Shortcuts

Use Cmd on macOS and Ctrl on Windows (for example Ctrl + Shift + S). Tooltips in the app always show the keys of the running platform.

Shortcut (macOS / Windows)	Action	Description
Cmd / Ctrl + S	Full Screenshot	Captures full phone screen to your Downloads folder & clipboard
Cmd + Shift + S	Area Screenshot	Drag interactive marquee to crop custom screen region
Cmd + Shift + R	Screen Recording	Hardware H.264 MP4 recording (up to 3 minutes) with countdown HUD & timer
Cmd + Shift + I	APK Manager	Inspect package metadata, configure install flags & sideload
Cmd + Shift + D	Intent Dispatcher	Fire deep link URLs, system intents & typed extras
Cmd + Shift + F	Device Files	Browse phone directories & download files to the computer
Cmd + Shift + L	Device Logcat	Real-time log stream with level/tag/PID filtering & export
Cmd + O	Screen-Off Toggle	Turn the phone's screen off or on; mirroring continues
Cmd + K	Text Injection	Open the text input modal (any language, emoji included)
Cmd + H / Backspace	Home / Back	Standard Android navigation controls

---

🏗️ Architecture

flowchart LR
    subgraph AndroidDevice ["📱 Android Device"]
        A1["SurfaceControl / Display Capture"] --> A2["MediaCodec (H.264 hardware)"]
        A2 --> A3["scrcpy-server (Shell-level daemon)"]
        A4["InputManager (Touch / Key Injection)"] <--- A3
    end

    subgraph Transport ["📶 Local Wi-Fi (LAN) / 🔌 USB Cable"]
        V_STREAM["TCP Video Stream (Raw NAL Units)"]
        A_STREAM["TCP Audio Stream (Raw PCM, Android 11+)"]
        C_SOCKET["TCP Control Socket (scrcpy Control Messages)"]
    end

    subgraph DesktopApp ["💻 macOS / Windows (Azdroid App - Flutter)"]
        M1["Flutter UI"] --> M2["Mouse & Keyboard Event Listener"]
        M3["Native Video Decoder (VideoToolbox / Media Foundation) → Texture"] --> M1
    end

    A3 === V_STREAM ===> M3
    A3 === A_STREAM ===> M4["Native Audio Player (AVAudioEngine / WASAPI)"]
    M2 === C_SOCKET ===> A3

---

🛠️ Quick Start & Installation

Prerequisites

	macOS	Windows (Preview)
Host	macOS 12.0+ (Apple Silicon or Intel)	Windows 10/11 x64
ADB	Bundled in release builds (optional: brew install android-platform-tools)	Bundled in release builds (optional: winget install Google.PlatformTools)
Android	5.0+ with USB Debugging enabled	Same

Install a release

• macOS: unzip Azdroid-v1.4.1-macOS.zip, move Azdroid.app to /Applications. Unsigned build: run xattr -cr /Applications/Azdroid.app once if Gatekeeper blocks it.
• Windows: unzip Azdroid-v1.4.1-Windows-x64.zip (ADB included) and run Azdroid\desk_droid.exe (no installer). Unsigned build: on the SmartScreen prompt choose More info → Run anyway.

Run from source

# 1. Clone repository
git clone https://github.com/az-coder-123/azdroid.git
cd azdroid

# 2. Install dependencies & launch
flutter pub get
flutter run -d macos     # macOS
flutter run -d windows   # Windows (needs Visual Studio 2022 with "Desktop development with C++")

Build a release package

./scripts/build_release.sh                                            # macOS → RELEASE/Azdroid-v<version>-macOS.zip
powershell -ExecutionPolicy Bypass -File scripts\build_release.ps1     # Windows → RELEASE\Azdroid-v<version>-Windows-x64.zip

Full setup, ADB drivers, and packaging options: Installation & Building. Publishing a release: Release Guide.

---

📚 Documentation Hub

Guide	Scope
💿 Installation & Building	Install on macOS or Windows, set up ADB, run from source, and package a release
🚀 Release Guide	Step-by-step release procedure: version, notes, build, package, upload, README links
🖥️ Platform Support	What works on macOS and Windows, and where the platforms differ
📖 User Guide	Getting started, first-time setup, and device permissions
📶 Pairing Guide	Wireless pairing instructions for Android 11+ and USB fallback
⌨️ Shortcuts & Gestures	Complete mouse gestures and keyboard shortcuts (Cmd on macOS, Ctrl on Windows)
⚡️ Features Catalog	Modular in-depth documentation across all 16 built-in features
🏛️ Architecture	Clean Architecture blueprint, BLoC state model, and socket protocols
🧭 Dependency Boundaries	Allowed imports between features, shared kernel, and composition root
🧩 Platform Abstraction	Where macOS/Windows differences live, and how to add a new one
🎞️ Native Video Contract	MethodChannel, scrcpy wire format, and rules shared by the Swift and C++ plugins
📦 Bundled Platform-Tools	How adb ships inside the app, how it is found, and how to upgrade it
🧮 scrcpy Upgrade Assessment	Why v2.1 must be upgraded, protocol compatibility by version, and the recommended path
🪟 Windows Port Plan	Phases, status, and risks of the Windows port
🛠️ Troubleshooting	Solutions for Xiaomi/MIUI input permissions, firewalls, and ADB errors
💡 Lessons Learned	Engineering post-mortems, root cause analyses, and edge-case solutions
🤖 AI Agent & MCP Guide	Connect Claude Desktop, Cursor, and Antigravity to automate Android devices (38 tools; Workflow Guide; App & Game Development)
🛡️ MCP Tool Safety	Which MCP tools need confirmation, how coordinates and text are read, and the protocol revision

---

🏷️ Search Keywords & Tags

android-screen-mirroring · scrcpy-macos-gui · scrcpy-windows-gui · wireless-adb · screen-mirror-mac · screen-mirror-windows · flutter-desktop · apple-silicon · android-logcat-gui · apk-installer-mac · deep-link-tester · android-file-transfer-mac · low-latency-streaming · open-source

---

🤝 Community, Contributing & License

🤝 Contributing Contributions, feature requests, and bug reports are warmly welcome! Azdroid thrives on community feedback. Found a bug? Submit a detailed GitHub Issue. Have a feature idea? Share it in Feature Requests. Want to contribute code? Fork, branch, and open a Pull Request.

📄 License & Freedom Azdroid is 100% free, open-source, and privacy-respecting software released under the MIT License. You are free to use, modify, distribute, and integrate this software into personal or commercial workflows. See LICENSE for full legal terms.

Developed and maintained by az-coder-123