Android-MCP never works when installed from repository via uvx — requires manual local installation

[YodaDmytro]

Same issue as with Windows-MCP from the same author — Android-MCP consistently fails to start when installed via uvx from PyPI. The server never connects.

The only working method is manual clone + local install:

1. git clone https://github.com/CursorTouch/Android-MCP.git
2. cd Android-MCP
3. uv sync
4. Configure with local uv --directory path

The recommended uvx method from README never works.

Environment: Windows 11, Python 3.14.2, uv latest, Claude Desktop

[YodaDmytro]

Windows MCP now successfully works!!

but Android MCP has the problem:

Android-MCP: Bug Report — Repository Installation Fails in Claude Desktop

Issue

android-mcp installed from Claude Desktop's built-in repository integration crashes on startup. The same windows-mcp from the same developer works perfectly.

---

Environment

Component	Version
OS	Windows 11 24H2 (ARM64, Snapdragon X Elite)
Python	3.14.2
uv/uvx	0.9.26
Claude Desktop	Latest (Feb 2026)
FastMCP	3.0.1
Device	Samsung Galaxy (WiFi ADB: 192.168.1.3:5555)

---

What Works ✅

1. windows-mcp from repository (uvx)

Config:

"windows-mcp": {
  "command": "uvx",
  "args": ["windows-mcp"]
}

Result: Connects successfully, all tools available (App, Shell, Snapshot, Click, Type, Scroll, Move, Shortcut, Wait, Scrape, MultiSelect, MultiEdit, Clipboard, Process, SystemInfo, Notification, LockScreen, Registry).

Log confirms handshake:

Starting MCP server 'windows-mcp' with transport 'stdio'
serverInfo: {"name":"windows-mcp","version":"3.0.1"}

2. uvx android-mcp from terminal

$ uvx android-mcp
Starting MCP server 'Android-MCP' with transport 'stdio'

Starts cleanly, no errors. (Without --device flag it just starts the server without connecting to a device.)

3. android-mcp local installation with --device flag

Config:

"android-mcp": {
  "command": "uv",
  "args": ["--directory", "D:\\Programs\\Claude\\Android-MCP", "run", "android-mcp", "--device", "192.168.1.3:5555"]
}

Result: Works when device is connected via WiFi ADB.

---

What Fails ❌

android-mcp from repository (Claude Desktop built-in integration)

Installation path: C:\Users\dmitr\AppData\Roaming\Claude\Claude Extensions\ant.dir.gh.cursortouch.android-mcp

The problem: Claude Desktop installs android-mcp via repository and runs it with:

uv --directory "C:\Users\dmitr\AppData\Roaming\Claude\Claude Extensions\ant.dir.gh.cursortouch.android-mcp" run android-mcp

Note: NO --device argument is passed. Because of this, the code falls back to the default:

# __main__.py, line 26:
mobile=Mobile(device=args.device if args.device else 'emulator-5554')

The default device is emulator-5554, which doesn't exist. This causes:

uiautomator2.exceptions.ConnectError: device emulator-5554 not online
ConnectionError: Failed to connect to device emulator-5554: device emulator-5554 not online

The server crashes before it can respond to the MCP initialize message, so Claude Desktop shows "Error connecting to MCP server."

---

Root Cause Analysis

Two separate issues:

Issue 1: No way to pass --device argument via repository installation

When installing from Claude Desktop's repository, there's no mechanism to specify --device 192.168.1.3:5555. Claude Desktop runs the server with just uv --directory ... run android-mcp and no additional args. The code then defaults to emulator-5554.

Comparison with windows-mcp: windows-mcp doesn't need a device argument — it operates on the local desktop. android-mcp requires a device serial, but the repository integration doesn't provide a way to configure this.

Issue 2: Server crashes on missing device instead of starting gracefully

Even without a device, the MCP server could start and expose tools that fail gracefully when called. Instead, the server crashes during initialization (__main__.py line 26), before the MCP handshake completes.

The code attempts to connect to the device at import/startup time:

mobile=Mobile(device=args.device if args.device else 'emulator-5554')

This should be deferred — connect to device lazily when a tool is actually called, not at server startup.

---

Evidence from Logs

Timeline from mcp-server-Android-MCP.log:

Feb 21, 20:20 — First attempt. Downloads 93 packages (6.88s). Crashes: device emulator-5554 not online

Feb 21, 20:20-20:30 — Claude Desktop retries ~8 times automatically. Same crash every time.

Feb 21, 21:31 — Both repository AND local instances run simultaneously:

• Repository (Android-MCP): Crashes with device emulator-5554 not online
• Local (android-mcp): Crashes with device RFCN2013V8D not online (USB serial, phone was disconnected at the time)

Feb 22, 15:08 — Current state:

• Local (android-mcp): Successfully connects, tools listed, MCP handshake complete ✅
• Repository (Android-MCP): Still crashes with device emulator-5554 not online ❌

---

Suggested Fixes

For the developer:

1. Lazy device connection. Don't connect to the device in __init__. Start the MCP server first, then connect when a tool is called. If no device is configured, tools should return an error message like "No device configured. Use --device flag."

2. Environment variable support. Allow ANDROID_MCP_DEVICE env var as an alternative to --device. Claude Desktop's config supports env blocks, so users could configure:

{
  "command": "uvx",
  "args": ["android-mcp"],
  "env": {
    "ANDROID_MCP_DEVICE": "192.168.1.3:5555"
  }
}

3. Auto-detect device. If no --device specified, run adb devices and use the first available device instead of defaulting to emulator-5554.

4. Connection type selection. Add a --connection or --transport flag to choose between WiFi and USB connections. Currently the user has to know the exact device identifier format:

   • USB: --device RFCN2013V8D (serial number)
   • WiFi: --device 192.168.1.3:5555 (IP:port)

   It would be much more user-friendly to support something like:

   android-mcp --wifi 192.168.1.3      # auto-appends :5555
   android-mcp --usb                    # auto-detects USB device
   android-mcp --usb RFCN2013V8D        # specific USB device
   

   Or via env vars for repository installation:

   {
     "env": {
       "ANDROID_MCP_CONNECTION": "wifi",
       "ANDROID_MCP_HOST": "192.168.1.3"
     }
   }

   Real-world context: My device (Samsung Galaxy, serial RFCN2013V8D) connects via both USB and WiFi ADB. When on WiFi it's 192.168.1.3:5555, when on USB it's RFCN2013V8D. Switching between them currently requires manually editing the config. Ideally the server should support both and auto-detect which is available.

For the user (current workaround):

Use local installation with explicit --device:

"android-mcp": {
  "command": "uv",
  "args": ["--directory", "D:\\Programs\\Claude\\Android-MCP", "run", "android-mcp", "--device", "192.168.1.3:5555"]
}

---

Reproduction Steps

1. Install android-mcp from Claude Desktop's MCP repository
2. Have a physical Android device connected via WiFi ADB (adb connect 192.168.1.3:5555)
3. Restart Claude Desktop
4. Observe: Android-MCP shows "Error connecting" despite device being available

Expected: Server should detect the WiFi-connected device
Actual: Server tries to connect to emulator-5554 (hardcoded default) and crashes

---

Comparison: windows-mcp vs android-mcp (Same Developer)

Aspect	windows-mcp	android-mcp
uvx install	✅ Works	✅ Works (terminal only)
Claude Desktop repo	✅ Works	❌ Crashes
Needs device arg	No (operates locally)	Yes (--device)
Default behavior	Works out of box	Crashes (no emulator)
Startup	Graceful	Crashes before MCP handshake
Repository	CursorTouch/Windows-MCP	CursorTouch/Android-MCP

[Jeomon]

I pushed new changes pls check

[OnlyTerp]

I'd like to work on this issue. I've analyzed the codebase and have a fix ready.

[NMichas]

+1
It would be very helpful to support options such as the ones mentioned by @YodaDmytro.