agi-android-mcp 0.0.1__tar.gz

agi_android_mcp-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agi_android_mcp-0.0.1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.env

agi_android_mcp-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AGI Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agi_android_mcp-0.0.1/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: agi-android-mcp
+Version: 0.0.1
+Summary: Control any Android phone from Claude, Cursor, or any MCP client — via ADB
+Project-URL: Homepage, https://github.com/agi-inc/agi-android-mcp
+Project-URL: Repository, https://github.com/agi-inc/agi-android-mcp
+Project-URL: Issues, https://github.com/agi-inc/agi-android-mcp/issues
+Author-email: AGI Inc <tech@agi.tech>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adb,android,automation,claude,llm,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# agi-android-mcp
+
+Control any Android phone from Claude Code, Cursor, or any MCP client — just ADB, no app required.
+
+![Demo](demo_screenshot.png)
+
+## How it works
+
+```
+Claude Code  ──(MCP stdio)──►  agi-android-mcp  ──(ADB)──►  Android Phone
+```
+
+A lightweight Python MCP server that translates tool calls into `adb` commands. Works with any Android phone that has USB debugging enabled. No proprietary dependencies.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install agi-android-mcp
+```
+
+### 2. Plug in your phone
+
+Enable USB debugging (Settings > Developer options > USB debugging), connect via USB, and verify:
+
+```bash
+adb devices
+# emulator-5554    device
+```
+
+### 3. Add to Claude Code
+
+Add to `~/.claude/claude_code_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "command": "agi-android-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Code. That's it. Tell Claude:
+
+> "Take a screenshot of my phone"
+
+> "Open Chrome and search for the weather"
+
+> "Launch Settings and turn on dark mode"
+
+Claude will take screenshots, reason about the UI, and tap/type/swipe to accomplish the task.
+
+### Add to Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "command": "agi-android-mcp"
+    }
+  }
+}
+```
+
+### Any MCP client
+
+The server uses stdio transport. Run `agi-android-mcp` as the command — it speaks MCP over stdin/stdout.
+
+## Tools (18)
+
+| Tool | Description |
+|------|-------------|
+| `screenshot` | Take a screenshot, returned as PNG image |
+| `get_screen_size` | Get screen dimensions in pixels |
+| `tap(x, y)` | Tap at pixel coordinates |
+| `double_tap(x, y)` | Double-tap at pixel coordinates |
+| `long_press(x, y)` | Long-press at pixel coordinates |
+| `type_text(text)` | Type text into focused input field |
+| `press_key(key)` | Press a key (enter, backspace, tab, space, home, back) |
+| `swipe(direction)` | Swipe up/down/left/right from screen center |
+| `drag(start, end)` | Drag between two points |
+| `press_home()` | Press the Home button |
+| `press_back()` | Press the Back button |
+| `open_notifications()` | Open the notification shade |
+| `open_quick_settings()` | Open quick settings panel |
+| `launch_app(package)` | Launch an app by package name |
+| `get_current_app()` | Get the currently visible app/activity |
+| `list_installed_apps()` | List installed packages |
+| `shell(command)` | Run any ADB shell command |
+| `get_device_info()` | Get device model, Android version, screen size, battery |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ADB_PATH` | Auto-detected | Path to `adb` binary |
+| `ADB_SERIAL` | (none) | Target a specific device by serial number |
+
+Multiple devices? Set `ADB_SERIAL`:
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "command": "agi-android-mcp",
+      "env": {
+        "ADB_SERIAL": "XXXXXXXXXXXXXX"
+      }
+    }
+  }
+}
+```
+
+## Agentic Demo
+
+`demo.py` runs a full autonomous loop: screenshot → Claude reasons → execute action → repeat.
+
+```bash
+pip install anthropic
+ANTHROPIC_API_KEY=sk-... python demo.py "Open Chrome and search for cats"
+```
+
+## How It Works
+
+1. MCP server starts over stdio (standard MCP transport)
+2. When a tool is called, it translates to an `adb` subprocess call
+3. Screenshots: `adb exec-out screencap -p`
+4. Input: `adb shell input tap/swipe/text/keyevent`
+5. Apps: `adb shell am`, `adb shell pm`
+
+## Development
+
+```bash
+pip install -e .
+python -c "from agi_android_mcp.server import mcp; print(len(mcp._tool_manager._tools), 'tools')"
+```
+
+## License
+
+MIT

agi_android_mcp-0.0.1/README.md

@@ -0,0 +1,145 @@
+# agi-android-mcp
+
+Control any Android phone from Claude Code, Cursor, or any MCP client — just ADB, no app required.
+
+![Demo](demo_screenshot.png)
+
+## How it works
+
+```
+Claude Code  ──(MCP stdio)──►  agi-android-mcp  ──(ADB)──►  Android Phone
+```
+
+A lightweight Python MCP server that translates tool calls into `adb` commands. Works with any Android phone that has USB debugging enabled. No proprietary dependencies.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install agi-android-mcp
+```
+
+### 2. Plug in your phone
+
+Enable USB debugging (Settings > Developer options > USB debugging), connect via USB, and verify:
+
+```bash
+adb devices
+# emulator-5554    device
+```
+
+### 3. Add to Claude Code
+
+Add to `~/.claude/claude_code_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "command": "agi-android-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Code. That's it. Tell Claude:
+
+> "Take a screenshot of my phone"
+
+> "Open Chrome and search for the weather"
+
+> "Launch Settings and turn on dark mode"
+
+Claude will take screenshots, reason about the UI, and tap/type/swipe to accomplish the task.
+
+### Add to Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "command": "agi-android-mcp"
+    }
+  }
+}
+```
+
+### Any MCP client
+
+The server uses stdio transport. Run `agi-android-mcp` as the command — it speaks MCP over stdin/stdout.
+
+## Tools (18)
+
+| Tool | Description |
+|------|-------------|
+| `screenshot` | Take a screenshot, returned as PNG image |
+| `get_screen_size` | Get screen dimensions in pixels |
+| `tap(x, y)` | Tap at pixel coordinates |
+| `double_tap(x, y)` | Double-tap at pixel coordinates |
+| `long_press(x, y)` | Long-press at pixel coordinates |
+| `type_text(text)` | Type text into focused input field |
+| `press_key(key)` | Press a key (enter, backspace, tab, space, home, back) |
+| `swipe(direction)` | Swipe up/down/left/right from screen center |
+| `drag(start, end)` | Drag between two points |
+| `press_home()` | Press the Home button |
+| `press_back()` | Press the Back button |
+| `open_notifications()` | Open the notification shade |
+| `open_quick_settings()` | Open quick settings panel |
+| `launch_app(package)` | Launch an app by package name |
+| `get_current_app()` | Get the currently visible app/activity |
+| `list_installed_apps()` | List installed packages |
+| `shell(command)` | Run any ADB shell command |
+| `get_device_info()` | Get device model, Android version, screen size, battery |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ADB_PATH` | Auto-detected | Path to `adb` binary |
+| `ADB_SERIAL` | (none) | Target a specific device by serial number |
+
+Multiple devices? Set `ADB_SERIAL`:
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "command": "agi-android-mcp",
+      "env": {
+        "ADB_SERIAL": "XXXXXXXXXXXXXX"
+      }
+    }
+  }
+}
+```
+
+## Agentic Demo
+
+`demo.py` runs a full autonomous loop: screenshot → Claude reasons → execute action → repeat.
+
+```bash
+pip install anthropic
+ANTHROPIC_API_KEY=sk-... python demo.py "Open Chrome and search for cats"
+```
+
+## How It Works
+
+1. MCP server starts over stdio (standard MCP transport)
+2. When a tool is called, it translates to an `adb` subprocess call
+3. Screenshots: `adb exec-out screencap -p`
+4. Input: `adb shell input tap/swipe/text/keyevent`
+5. Apps: `adb shell am`, `adb shell pm`
+
+## Development
+
+```bash
+pip install -e .
+python -c "from agi_android_mcp.server import mcp; print(len(mcp._tool_manager._tools), 'tools')"
+```
+
+## License
+
+MIT

agi_android_mcp-0.0.1/demo.py

@@ -0,0 +1,460 @@
+#!/usr/bin/env python3
+"""
+AGI Android MCP Demo — Let Claude drive your phone via ADB.
+
+An agentic loop: screenshot -> Claude decides action -> execute via ADB -> repeat.
+
+Usage:
+    pip install anthropic
+    ANTHROPIC_API_KEY=sk-... python demo.py "Open Chrome and search for cats"
+
+Prerequisites:
+    1. ADB installed and in PATH
+    2. Android device connected with USB debugging enabled
+    3. Run 'adb devices' to verify connectivity
+"""
+
+import argparse
+import base64
+import os
+import shutil
+import subprocess
+import sys
+import time
+
+try:
+    import anthropic
+except ImportError:
+    print("Error: 'anthropic' package required. Install with: pip install anthropic")
+    sys.exit(1)
+
+# ---------------------------------------------------------------------------
+# Colors for terminal output
+# ---------------------------------------------------------------------------
+
+
+class C:
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    CYAN = "\033[36m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    MAGENTA = "\033[35m"
+    RED = "\033[31m"
+    BLUE = "\033[34m"
+    RESET = "\033[0m"
+
+
+BANNER = f"""{C.CYAN}{C.BOLD}
+    ___   ____________   ___              __           _     __
+   /   | / ____/  _/  | / / /___ ___  __/ /________  (_)___/ /
+  / /| |/ / __ / // /| |/ / __  / __|/ / __  / ___/ / / __  /
+ / ___ / /_/ // // ___ / / /_/ / /  / / /_/ / /  / / / /_/ /
+/_/  |_\\____/___/_/  |_/_/\\__,_/_/  /_/\\____/_/  /_/_/\\__,_/
+{C.RESET}{C.DIM}
+            Claude x ADB — Android MCP Demo
+{C.RESET}"""
+
+# ---------------------------------------------------------------------------
+# ADB helpers
+# ---------------------------------------------------------------------------
+
+ADB = os.environ.get("ADB_PATH", shutil.which("adb") or "adb")
+SERIAL = os.environ.get("ADB_SERIAL", "")
+
+
+def _adb(*args: str, timeout: float = 10.0) -> subprocess.CompletedProcess:
+    cmd = [ADB]
+    if SERIAL:
+        cmd += ["-s", SERIAL]
+    cmd += list(args)
+    return subprocess.run(cmd, capture_output=True, timeout=timeout)
+
+
+def _shell(*args: str, timeout: float = 10.0) -> str:
+    r = _adb("shell", *args, timeout=timeout)
+    return r.stdout.decode("utf-8", errors="replace").strip()
+
+
+# ---------------------------------------------------------------------------
+# Tools for Claude
+# ---------------------------------------------------------------------------
+
+SCREEN_W, SCREEN_H = 0, 0
+
+TOOLS = [
+    {
+        "name": "screenshot",
+        "description": "Take a screenshot of the Android screen. Call this to see what's on screen.",
+        "input_schema": {"type": "object", "properties": {}, "required": []},
+    },
+    {
+        "name": "tap",
+        "description": "Tap at (x, y) pixel coordinates on the screen.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "x": {"type": "number", "description": "X coordinate in pixels"},
+                "y": {"type": "number", "description": "Y coordinate in pixels"},
+            },
+            "required": ["x", "y"],
+        },
+    },
+    {
+        "name": "type_text",
+        "description": "Type text into the currently focused input field.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "text": {"type": "string", "description": "Text to type"},
+            },
+            "required": ["text"],
+        },
+    },
+    {
+        "name": "swipe",
+        "description": "Swipe the screen in a direction (up/down/left/right).",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "direction": {
+                    "type": "string",
+                    "enum": ["up", "down", "left", "right"],
+                },
+            },
+            "required": ["direction"],
+        },
+    },
+    {
+        "name": "press_key",
+        "description": "Press a key: enter, back, home, backspace.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "key": {
+                    "type": "string",
+                    "enum": ["enter", "back", "home", "backspace"],
+                },
+            },
+            "required": ["key"],
+        },
+    },
+    {
+        "name": "launch_app",
+        "description": "Launch an Android app by package name.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "package": {"type": "string", "description": "e.g. com.android.chrome"},
+            },
+            "required": ["package"],
+        },
+    },
+    {
+        "name": "long_press",
+        "description": "Long-press at (x, y) pixel coordinates.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "x": {"type": "number"},
+                "y": {"type": "number"},
+            },
+            "required": ["x", "y"],
+        },
+    },
+    {
+        "name": "done",
+        "description": "Call this when the task is complete. Include a summary of what you did.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "summary": {"type": "string", "description": "What was accomplished"},
+            },
+            "required": ["summary"],
+        },
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Pretty output helpers
+# ---------------------------------------------------------------------------
+
+
+def log_step(step: int, max_steps: int):
+    bar_len = 30
+    filled = int(bar_len * step / max_steps)
+    bar = "=" * filled + "-" * (bar_len - filled)
+    print(f"\n{C.BLUE}{C.BOLD}[{bar}] Step {step}/{max_steps}{C.RESET}")
+
+
+def log_thinking(text: str):
+    for line in text.split("\n"):
+        print(f"  {C.DIM}{line}{C.RESET}")
+
+
+def log_action(name: str, args: dict):
+    args_str = ""
+    if name == "tap":
+        args_str = f"({args['x']}, {args['y']})"
+    elif name == "type_text":
+        args_str = f'"{args["text"]}"'
+    elif name == "swipe":
+        args_str = args["direction"]
+    elif name == "press_key":
+        args_str = args["key"]
+    elif name == "launch_app":
+        args_str = args["package"]
+    elif name == "long_press":
+        args_str = f"({args['x']}, {args['y']})"
+    elif name == "screenshot":
+        args_str = "capturing..."
+    elif name == "done":
+        args_str = args.get("summary", "")[:60]
+    print(f"  {C.YELLOW}{C.BOLD}{name}{C.RESET} {C.DIM}{args_str}{C.RESET}")
+
+
+def log_result(name: str, elapsed_ms: int):
+    print(f"  {C.GREEN}done{C.RESET} {C.DIM}({elapsed_ms}ms){C.RESET}")
+
+
+# ---------------------------------------------------------------------------
+# Tool execution via ADB
+# ---------------------------------------------------------------------------
+
+
+def exec_tool(name: str, args: dict) -> list:
+    """Execute a tool call via ADB and return Anthropic content blocks."""
+
+    if name == "screenshot":
+        r = _adb("exec-out", "screencap", "-p", timeout=15.0)
+        if r.returncode != 0 or not r.stdout:
+            return [{"type": "text", "text": f"Screenshot failed: {r.stderr.decode()}"}]
+        b64 = base64.standard_b64encode(r.stdout).decode("ascii")
+        return [
+            {"type": "text", "text": f"Here is the current screen ({SCREEN_W}x{SCREEN_H}):"},
+            {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": "image/png",
+                    "data": b64,
+                },
+            },
+        ]
+
+    elif name == "tap":
+        x, y = int(args["x"]), int(args["y"])
+        _shell("input", "tap", str(x), str(y))
+        return [{"type": "text", "text": f"Tapped ({x}, {y})"}]
+
+    elif name == "type_text":
+        text = args["text"]
+        escaped = text.replace(" ", "%s")
+        escaped = escaped.replace("'", "\\'")
+        escaped = escaped.replace('"', '\\"')
+        escaped = escaped.replace("&", "\\&")
+        escaped = escaped.replace("|", "\\|")
+        escaped = escaped.replace(";", "\;")
+        escaped = escaped.replace("(", "\\(")
+        escaped = escaped.replace(")", "\\)")
+        _shell("input", "text", escaped)
+        return [{"type": "text", "text": f"Typed: {text}"}]
+
+    elif name == "swipe":
+        direction = args["direction"]
+        cx, cy = SCREEN_W // 2, SCREEN_H // 2
+        dist = int(0.35 * SCREEN_H)
+        if direction == "up":
+            ex, ey = cx, cy - dist
+        elif direction == "down":
+            ex, ey = cx, cy + dist
+        elif direction == "left":
+            ex, ey = cx - dist, cy
+        elif direction == "right":
+            ex, ey = cx + dist, cy
+        else:
+            return [{"type": "text", "text": f"Invalid direction: {direction}"}]
+        _shell("input", "swipe", str(cx), str(cy), str(ex), str(ey), "300")
+        return [{"type": "text", "text": f"Swiped {direction}"}]
+
+    elif name == "press_key":
+        key = args["key"]
+        keymap = {"enter": "66", "backspace": "67", "back": "4", "home": "3"}
+        keycode = keymap.get(key, key)
+        _shell("input", "keyevent", keycode)
+        return [{"type": "text", "text": f"Pressed {key}"}]
+
+    elif name == "launch_app":
+        package = args["package"]
+        _shell("monkey", "-p", package, "-c", "android.intent.category.LAUNCHER", "1")
+        return [{"type": "text", "text": f"Launched {package}"}]
+
+    elif name == "long_press":
+        x, y = int(args["x"]), int(args["y"])
+        _shell("input", "swipe", str(x), str(y), str(x), str(y), "1000")
+        return [{"type": "text", "text": f"Long-pressed ({x}, {y})"}]
+
+    elif name == "done":
+        return [{"type": "text", "text": args["summary"]}]
+
+    return [{"type": "text", "text": f"Unknown tool: {name}"}]
+
+
+# ---------------------------------------------------------------------------
+# Agent loop
+# ---------------------------------------------------------------------------
+
+SYSTEM = """\
+You are an Android phone operator. You can see the screen via screenshots and \
+interact using tap, type_text, swipe, press_key, launch_app, and long_press.
+
+Screen coordinates are in pixels. The screen is {w}x{h}.
+
+Strategy:
+1. Always start by taking a screenshot to see the current state.
+2. Decide on one action at a time.
+3. After each action, take another screenshot to verify the result.
+4. When the task is complete, call the `done` tool with a summary.
+
+Be precise with coordinates — look carefully at the screenshot to identify \
+where UI elements are before tapping.\
+"""
+
+
+def run(task: str, max_steps: int = 25, model: str = "claude-sonnet-4-5-20250929"):
+    global SCREEN_W, SCREEN_H
+
+    client = anthropic.Anthropic()
+
+    # Check ADB connectivity
+    print(f"  {C.DIM}Checking ADB connection...{C.RESET}")
+    r = _adb("devices", timeout=5.0)
+    output = r.stdout.decode("utf-8", errors="replace")
+    device_lines = [l for l in output.strip().splitlines()[1:] if l.strip()]
+    if not device_lines:
+        print(f"  {C.RED}{C.BOLD}Error:{C.RESET} {C.RED}No ADB devices found.{C.RESET}")
+        print(f"  Connect a device with USB debugging enabled and run 'adb devices'.")
+        sys.exit(1)
+
+    # Get screen size
+    try:
+        wm_output = _shell("wm", "size")
+        for line in wm_output.splitlines():
+            if "Physical size" in line:
+                dims = line.split(":")[-1].strip()
+                w, h = dims.split("x")
+                SCREEN_W, SCREEN_H = int(w), int(h)
+                break
+        if SCREEN_W == 0:
+            SCREEN_W, SCREEN_H = 1080, 2400
+    except Exception:
+        SCREEN_W, SCREEN_H = 1080, 2400
+
+    print(f"  {C.GREEN}Connected{C.RESET} | Screen: {SCREEN_W}x{SCREEN_H}")
+    print(f"  {C.DIM}Model: {model}{C.RESET}")
+    print(f"  {C.MAGENTA}{C.BOLD}Task:{C.RESET} {task}")
+
+    system_prompt = SYSTEM.format(w=SCREEN_W, h=SCREEN_H)
+    messages = [{"role": "user", "content": f"Task: {task}"}]
+    total_tokens = 0
+    start_time = time.time()
+
+    for step in range(1, max_steps + 1):
+        log_step(step, max_steps)
+
+        t0 = time.time()
+        response = client.messages.create(
+            model=model,
+            max_tokens=1024,
+            system=system_prompt,
+            tools=TOOLS,
+            messages=messages,
+        )
+        api_ms = int((time.time() - t0) * 1000)
+        total_tokens += response.usage.input_tokens + response.usage.output_tokens
+
+        print(
+            f"  {C.DIM}API: {api_ms}ms | tokens: "
+            f"+{response.usage.input_tokens + response.usage.output_tokens}{C.RESET}"
+        )
+
+        # Process response
+        assistant_content = response.content
+        messages.append({"role": "assistant", "content": assistant_content})
+
+        # Show Claude's thinking
+        for block in assistant_content:
+            if block.type == "text" and block.text:
+                log_thinking(block.text)
+
+        # Check stop
+        if response.stop_reason == "end_turn":
+            print(f"\n  {C.DIM}Claude finished (no more tool calls).{C.RESET}")
+            break
+
+        # Execute tool calls
+        tool_results = []
+        finished = False
+        for block in assistant_content:
+            if block.type != "tool_use":
+                continue
+
+            name = block.name
+            args = block.input
+            log_action(name, args)
+
+            t0 = time.time()
+            result_content = exec_tool(name, args)
+            exec_ms = int((time.time() - t0) * 1000)
+            log_result(name, exec_ms)
+
+            tool_results.append(
+                {
+                    "type": "tool_result",
+                    "tool_use_id": block.id,
+                    "content": result_content,
+                }
+            )
+
+            if name == "done":
+                finished = True
+                print(f"\n{C.GREEN}{C.BOLD}Task Complete{C.RESET}")
+                print(f"  {args['summary']}")
+
+        messages.append({"role": "user", "content": tool_results})
+
+        if finished:
+            break
+    else:
+        print(f"\n  {C.YELLOW}Reached max steps ({max_steps}).{C.RESET}")
+
+    elapsed = time.time() - start_time
+    print(f"\n{C.DIM}  {elapsed:.1f}s total | {total_tokens:,} tokens{C.RESET}")
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Let Claude drive your Android phone via ADB.",
+        epilog='Example: python demo.py "Open Settings and enable dark mode"',
+    )
+    parser.add_argument("task", help="What you want Claude to do on the phone")
+    parser.add_argument("--steps", type=int, default=25, help="Max steps (default 25)")
+    parser.add_argument(
+        "--model",
+        default="claude-sonnet-4-5-20250929",
+        help="Anthropic model (default: claude-sonnet-4-5-20250929)",
+    )
+    args = parser.parse_args()
+
+    print(BANNER)
+    run(args.task, max_steps=args.steps, model=args.model)
+
+
+if __name__ == "__main__":
+    main()

agi_android_mcp-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agi-android-mcp"
+version = "0.0.1"
+description = "Control any Android phone from Claude, Cursor, or any MCP client — via ADB"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "AGI Inc", email = "tech@agi.tech" },
+]
+keywords = ["android", "mcp", "adb", "llm", "claude", "automation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/agi-inc/agi-android-mcp"
+Repository = "https://github.com/agi-inc/agi-android-mcp"
+Issues = "https://github.com/agi-inc/agi-android-mcp/issues"
+
+[project.scripts]
+agi-android-mcp = "agi_android_mcp.server:main"

agi_android_mcp-0.0.1/src/agi_android_mcp/__init__.py

@@ -0,0 +1 @@
+"""AGI Android MCP Server — ADB transport."""

agi_android_mcp-0.0.1/src/agi_android_mcp/server.py

@@ -0,0 +1,393 @@
+"""
+AGI Android MCP Server — control any Android device via ADB.
+
+All device interaction goes through `adb` subprocess calls.
+No proprietary dependencies, works with any Android phone that has USB debugging enabled.
+"""
+
+import base64
+import os
+import shutil
+import subprocess
+import time
+
+from mcp.server.fastmcp import FastMCP, Image
+
+# ---------------------------------------------------------------------------
+# ADB helpers
+# ---------------------------------------------------------------------------
+
+ADB = os.environ.get("ADB_PATH", shutil.which("adb") or "adb")
+SERIAL = os.environ.get("ADB_SERIAL", "")
+
+
+def _adb(*args: str, timeout: float = 10.0) -> subprocess.CompletedProcess:
+    """Run an adb command and return the CompletedProcess."""
+    cmd = [ADB]
+    if SERIAL:
+        cmd += ["-s", SERIAL]
+    cmd += list(args)
+    return subprocess.run(cmd, capture_output=True, timeout=timeout)
+
+
+def _shell(*args: str, timeout: float = 10.0) -> str:
+    """Run `adb shell <args>` and return stdout as a stripped string."""
+    r = _adb("shell", *args, timeout=timeout)
+    return r.stdout.decode("utf-8", errors="replace").strip()
+
+
+def _check_connection() -> str:
+    """Verify an ADB device is connected and reachable."""
+    r = _adb("devices", timeout=5.0)
+    output = r.stdout.decode("utf-8", errors="replace")
+    lines = [l for l in output.strip().splitlines()[1:] if l.strip()]
+
+    if not lines:
+        raise RuntimeError(
+            "No ADB devices found. Connect a device with USB debugging enabled "
+            "and run 'adb devices' to verify."
+        )
+
+    for line in lines:
+        parts = line.split("\t")
+        if len(parts) >= 2:
+            serial, state = parts[0], parts[1]
+            if SERIAL and serial != SERIAL:
+                continue
+            if state == "offline":
+                raise RuntimeError(f"Device {serial} is offline.")
+            if state == "device":
+                return serial
+
+    if SERIAL:
+        raise RuntimeError(
+            f"Device with serial '{SERIAL}' not found. "
+            f"Available devices:\n{output}"
+        )
+    raise RuntimeError(f"No usable ADB device found. Output:\n{output}")
+
+
+# ---------------------------------------------------------------------------
+# MCP Server
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP(
+    "AGI Android MCP",
+    instructions="Control any Android phone via ADB — tap, swipe, type, screenshot, and more.",
+)
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def screenshot() -> Image:
+    """Take a screenshot of the Android screen. Returns the current screen as a PNG image."""
+    _check_connection()
+    r = _adb("exec-out", "screencap", "-p", timeout=15.0)
+    if r.returncode != 0:
+        raise RuntimeError(
+            f"screencap failed: {r.stderr.decode('utf-8', errors='replace')}"
+        )
+    png_bytes = r.stdout
+    if not png_bytes or len(png_bytes) < 8:
+        raise RuntimeError("screencap returned empty data")
+    return Image(data=png_bytes, format="png")
+
+
+@mcp.tool()
+def get_screen_size() -> dict:
+    """Get the physical screen size of the Android device in pixels."""
+    _check_connection()
+    output = _shell("wm", "size")
+    # Example: "Physical size: 1080x2400"
+    for line in output.splitlines():
+        if "Physical size" in line:
+            dims = line.split(":")[-1].strip()
+            w, h = dims.split("x")
+            return {"width": int(w), "height": int(h)}
+    # Fallback: try parsing override or whatever is there
+    if "x" in output:
+        parts = output.strip().splitlines()[-1]
+        dims = parts.split(":")[-1].strip() if ":" in parts else parts.strip()
+        if "x" in dims:
+            w, h = dims.split("x")
+            return {"width": int(w.strip()), "height": int(h.strip())}
+    raise RuntimeError(f"Could not parse screen size from: {output}")
+
+
+@mcp.tool()
+def tap(x: int, y: int) -> str:
+    """Tap at (x, y) pixel coordinates on the screen."""
+    _check_connection()
+    _shell("input", "tap", str(x), str(y))
+    return f"Tapped ({x}, {y})"
+
+
+@mcp.tool()
+def double_tap(x: int, y: int) -> str:
+    """Double-tap at (x, y) pixel coordinates on the screen."""
+    _check_connection()
+    _shell("input", "tap", str(x), str(y))
+    time.sleep(0.1)
+    _shell("input", "tap", str(x), str(y))
+    return f"Double-tapped ({x}, {y})"
+
+
+@mcp.tool()
+def long_press(x: int, y: int) -> str:
+    """Long-press at (x, y) pixel coordinates (holds for 1 second)."""
+    _check_connection()
+    _shell("input", "swipe", str(x), str(y), str(x), str(y), "1000")
+    return f"Long-pressed ({x}, {y})"
+
+
+@mcp.tool()
+def type_text(text: str) -> str:
+    """Type text into the currently focused input field.
+
+    Handles spaces and special characters automatically.
+    """
+    _check_connection()
+    # ADB input text doesn't handle spaces well — replace with %s
+    # Also escape shell-special characters
+    escaped = text.replace("\\", "\\\\")
+    escaped = escaped.replace(" ", "%s")
+    escaped = escaped.replace("'", "\\'")
+    escaped = escaped.replace('"', '\\"')
+    escaped = escaped.replace("&", "\\&")
+    escaped = escaped.replace("|", "\\|")
+    escaped = escaped.replace(";", "\\;")
+    escaped = escaped.replace("(", "\\(")
+    escaped = escaped.replace(")", "\\)")
+    escaped = escaped.replace("<", "\\<")
+    escaped = escaped.replace(">", "\\>")
+    escaped = escaped.replace("`", "\\`")
+    _shell("input", "text", escaped)
+    return f"Typed: {text}"
+
+
+@mcp.tool()
+def press_key(key: str) -> str:
+    """Press a key on the Android device.
+
+    Supported keys: enter, backspace, delete, tab, space, home, back,
+    menu, search, volume_up, volume_down, power, escape.
+    """
+    _check_connection()
+    keymap = {
+        "enter": "66",
+        "backspace": "67",
+        "delete": "112",
+        "tab": "61",
+        "space": "62",
+        "home": "3",
+        "back": "4",
+        "menu": "82",
+        "search": "84",
+        "volume_up": "24",
+        "volume_down": "25",
+        "power": "26",
+        "escape": "111",
+    }
+    keycode = keymap.get(key.lower())
+    if keycode is None:
+        # Try as raw KEYCODE_ value
+        _shell("input", "keyevent", key)
+        return f"Pressed key: {key}"
+    _shell("input", "keyevent", keycode)
+    return f"Pressed {key}"
+
+
+@mcp.tool()
+def swipe(direction: str, distance: int = 500, x: int = -1, y: int = -1) -> str:
+    """Swipe the screen in a direction.
+
+    Args:
+        direction: One of "up", "down", "left", "right".
+        distance: Swipe distance in pixels (default 500).
+        x: Starting X coordinate. Defaults to screen center.
+        y: Starting Y coordinate. Defaults to screen center.
+    """
+    _check_connection()
+    # Get screen size for centering
+    if x < 0 or y < 0:
+        size = get_screen_size()
+        if x < 0:
+            x = size["width"] // 2
+        if y < 0:
+            y = size["height"] // 2
+
+    direction = direction.lower()
+    if direction == "up":
+        ex, ey = x, y - distance
+    elif direction == "down":
+        ex, ey = x, y + distance
+    elif direction == "left":
+        ex, ey = x - distance, y
+    elif direction == "right":
+        ex, ey = x + distance, y
+    else:
+        raise ValueError(f"Invalid direction: {direction}. Use up/down/left/right.")
+
+    _shell("input", "swipe", str(x), str(y), str(ex), str(ey), "300")
+    return f"Swiped {direction} from ({x}, {y}) to ({ex}, {ey})"
+
+
+@mcp.tool()
+def drag(start_x: int, start_y: int, end_x: int, end_y: int) -> str:
+    """Drag from (start_x, start_y) to (end_x, end_y) with a 300ms duration."""
+    _check_connection()
+    _shell(
+        "input", "swipe",
+        str(start_x), str(start_y),
+        str(end_x), str(end_y),
+        "300",
+    )
+    return f"Dragged from ({start_x}, {start_y}) to ({end_x}, {end_y})"
+
+
+@mcp.tool()
+def press_home() -> str:
+    """Press the Home button."""
+    _check_connection()
+    _shell("input", "keyevent", "KEYCODE_HOME")
+    return "Pressed Home"
+
+
+@mcp.tool()
+def press_back() -> str:
+    """Press the Back button."""
+    _check_connection()
+    _shell("input", "keyevent", "KEYCODE_BACK")
+    return "Pressed Back"
+
+
+@mcp.tool()
+def open_notifications() -> str:
+    """Open the notification shade."""
+    _check_connection()
+    _shell("cmd", "statusbar", "expand-notifications")
+    return "Opened notifications"
+
+
+@mcp.tool()
+def open_quick_settings() -> str:
+    """Open the quick settings panel."""
+    _check_connection()
+    _shell("cmd", "statusbar", "expand-settings")
+    return "Opened quick settings"
+
+
+@mcp.tool()
+def launch_app(package: str) -> str:
+    """Launch an Android app by its package name (e.g. com.android.chrome)."""
+    _check_connection()
+    output = _shell(
+        "monkey", "-p", package,
+        "-c", "android.intent.category.LAUNCHER", "1",
+    )
+    if "No activities found" in output:
+        raise RuntimeError(
+            f"Could not launch '{package}': no launcher activity found. "
+            f"Check the package name with list_installed_apps()."
+        )
+    return f"Launched {package}"
+
+
+@mcp.tool()
+def get_current_app() -> str:
+    """Get the currently visible app (package name and activity)."""
+    _check_connection()
+    output = _shell("dumpsys", "activity", "activities", timeout=5.0)
+    for line in output.splitlines():
+        if "mResumedActivity" in line or "ResumedActivity" in line:
+            return line.strip()
+    return "Could not determine current activity"
+
+
+@mcp.tool()
+def list_installed_apps() -> list[str]:
+    """List third-party installed apps (package names)."""
+    _check_connection()
+    output = _shell("pm", "list", "packages", "-3", timeout=10.0)
+    packages = []
+    for line in output.splitlines():
+        line = line.strip()
+        if line.startswith("package:"):
+            packages.append(line[len("package:"):])
+    return sorted(packages)
+
+
+@mcp.tool()
+def shell(command: str) -> str:
+    """Run an arbitrary ADB shell command and return its output.
+
+    Use this for anything not covered by the other tools.
+    """
+    _check_connection()
+    result = _shell(command, timeout=15.0)
+    return result
+
+
+@mcp.tool()
+def get_device_info() -> dict:
+    """Get device information: screen size, Android version, model, and battery level."""
+    _check_connection()
+
+    # Screen size
+    screen = {}
+    try:
+        screen = get_screen_size()
+    except Exception as e:
+        screen = {"error": str(e)}
+
+    # Android version
+    android_version = _shell("getprop", "ro.build.version.release")
+
+    # Device model
+    model = _shell("getprop", "ro.product.model")
+
+    # Manufacturer
+    manufacturer = _shell("getprop", "ro.product.manufacturer")
+
+    # Battery
+    battery_output = _shell("dumpsys", "battery")
+    battery = {}
+    for line in battery_output.splitlines():
+        line = line.strip()
+        if line.startswith("level:"):
+            battery["level"] = int(line.split(":")[1].strip())
+        elif line.startswith("status:"):
+            status_code = int(line.split(":")[1].strip())
+            battery["status"] = {
+                1: "unknown",
+                2: "charging",
+                3: "discharging",
+                4: "not_charging",
+                5: "full",
+            }.get(status_code, str(status_code))
+
+    return {
+        "screen": screen,
+        "android_version": android_version,
+        "model": model,
+        "manufacturer": manufacturer,
+        "battery": battery,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main():
+    """Run the MCP server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()