AndroidBridge

AndroidBridge lets an MCP client (Claude Desktop, Cursor, etc.) on your laptop read and modify settings on a paired Android device over your local network. No cloud, no USB required.

How it works

Claude Desktop  ──stdio──►  mcp-server  ──HTTP/HMAC──►  Android app (Ktor :8765)
                                                              └─ Settings.System / Secure / Global

The Android app runs an embedded HTTP server (Ktor) secured with HMAC-SHA256. The laptop side discovers the device via mDNS and signs every request with a shared secret exchanged during pairing.

Prerequisites

| Tool | Version | |------|---------| | Node.js | ≥ 20 | | Android Studio | Hedgehog or newer | | JDK | 17 | | Android device | API 26+ (real device recommended; emulator works for most settings) |

Build & install the Android app

# 1. Build web assets
npm run build -w packages/android-app

# 2. Sync into the Android project
npx cap sync android -w packages/android-app

# 3. Open in Android Studio, then Run ▶
npx cap open android -w packages/android-app

Grant permissions

WRITE_SETTINGS (user-grantable)

Open the Permissions tab in the app and tap Grant WRITE_SETTINGS. This enables brightness, volume, screen timeout controls.

WRITE_SECURE_SETTINGS (optional, via ADB)

Required for airplane mode, location mode, Bluetooth state, and other Settings.Secure / Settings.Global keys.

adb shell pm grant com.androidbridge.app android.permission.WRITE_SECURE_SETTINGS

Pair with your laptop

1. Open the app on your Android device and go to the Pairing tab — a QR code and plain-text secret are displayed.
2. On your laptop:

npx @web4w3/android-desktop-bridge pair
# Paste the secret shown in the app when prompted

Config is saved to ~/.config/android-bridge/config.json.

Install the MCP server

npx -y @web4w3/android-desktop-bridge

No build step needed. The package is pre-compiled and available on npm as @web4w3/android-desktop-bridge.

npm run build -w packages/mcp-server
npm link -w packages/mcp-server      # makes `android-bridge` available globally

Wire into Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "android-bridge": {
      "command": "npx",
      "args": ["-y", "@web4w3/android-desktop-bridge"]
    }
  }
}

Restart Claude Desktop. The following tools will be available:

| Tool | Description | |------|-------------| | list_devices | Discover devices on the LAN | | get_device_info | Model, OS version, app version | | get_capabilities | Which permission tier is active | | get_setting <key> | Read a setting value | | set_setting <key> <value> | Write a setting value | | toggle_wifi | Open WiFi settings panel on device |

Supported setting keys: screen_brightness, screen_brightness_mode, screen_off_timeout, volume_ring, volume_notification, volume_alarm, volume_music, volume_system, accelerometer_rotation, font_scale, airplane_mode_on, bluetooth_on, location_mode, wifi_sleep_policy

CLI commands

npx @web4w3/android-desktop-bridge pair       # pair with a device
npx @web4w3/android-desktop-bridge discover   # list devices on the LAN
npx @web4w3/android-desktop-bridge status     # show current config

Troubleshooting

| Symptom | Fix | |---------|-----| | Device not found | Check same Wi-Fi subnet; mDNS must be allowed. Use --device-ip <ip> to bypass discovery. | | HTTP 401 | Re-run android-bridge pair — secret mismatch. | | set_setting returns TierUnavailable | Grant the required permission (see above). | | App killed in background | Start the server — it runs as a foreground service with a persistent notification. | | Emulator wifi toggle | WiFi panel intent requires a real device for actual toggling; emulator shows the panel. |

Testing

See TESTING.md for a step-by-step checklist covering building the Android app, granting permissions, pairing, and exercising every MCP tool against a real device.