Azdroid README | AllMCPs

⚡️ Azdroid — High-Performance Android Screen Mirroring & Workstation for macOS & Windows

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}

Azdroid mirroring workspace on macOS: the phone screen between two vertical control docks, with the latency, FPS, and bitrate header

🚀 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

Azdroid device list with two connected phones, a Wi-Fi/USB switch for a dual-mode device, and the MCP status icon

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

Azdroid Built-in Feature Showcase and Interactive Catalog

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

2. Developer Inspection: Logcat & Intent Dispatcher

Azdroid Real-Time Logcat Console with Multi-Tier Filters

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.}

Azdroid Deep Link Tester and Android Intent Dispatcher

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

3. App Deployment & Two-Way File Management

Azdroid 1-Click APK Sideload and Package Manager

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

Azdroid screen recording bar with a 3-second countdown and Start button over the mirrored phone

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.}

Azdroid area crop: a marquee with drag handles over the mirrored phone and Clipboard, Save File, and Both actions

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

5. Remote Text Input

Azdroid Remote Text Injection dialog over the mirrored phone, with a text field and Inject Text button
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:

mermaid

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_semantic_tree`, `android_take_screenshot`
3	👆 Touch & Action	Injecting multi-touch, typing, and key events	`android_tap`, `android_type_text`, `android_swipe`
4	🚨 Error Interception	Capturing stack traces, ANRs, and log buffers	`android_check_crash`, `android_get_logcat`
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

mermaid

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_semantic_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_type_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_check_crash & android_get_logcat
        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_semantic_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

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

mermaid

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.3.0-macOS.zip, move Azdroid.app to /Applications. Unsigned build: run xattr -cr /Applications/Azdroid.app once if Gatekeeper blocks it.
Windows: unzip Azdroid-v1.3.0-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

bash

# 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

bash

./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

🏷️ 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