Susu Phone Agent
Give Claude Code a real Android device.
Control a real Android phone from Claude Code through MCP + Shizuku — no root, no Claude credentials on the phone, no model polling.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
You
↓
Claude Code
↓ MCP tool call
Susu Phone MCP
↓ HTTPS job queue
Susu Phone Bridge
↓ polling (phone-initiated)
Android Agent APK
↓ Shizuku UserService (uid=2000)
📱 Real Android phone
TODO: add demo GIF — Claude types "Open Xiaohongshu" → app opens on real phone
Three components, all yours to host:
1. Phone MCP (mcp/phone_mcp.py) — a FastMCP stdio server. Claude Code calls it like any other MCP tool. It forwards requests to the Phone Bridge.
2. Phone Bridge (bridge/bridge.py) — a FastAPI job queue on your server. The MCP pushes jobs in; the Android APK pulls them out. Nothing is pushed to the phone.
3. Android Agent APK (android/) — a foreground service. Built with Shizuku in wireless ADB mode. No root required. The phone polls your Bridge over ordinary HTTPS. No AI inference happens on the device.
ADB over the internet is fragile, requires open ports, and breaks on network change. Inverting the connection — phone polls your server — works over mobile data, behind NAT, anywhere.
Accessibility services are heavily restricted on Android 13+. Shizuku provides direct shell-level access (uid=2000) via the wireless debugging channel already built into Android. Commands like input keyevent, dumpsys window, and monkey work reliably without root.
The Android device never receives Claude or Anthropic credentials. Claude Code invokes the MCP server locally on the host machine. Phone polling is ordinary HTTPS traffic — it does not invoke a model.
openssl rand -hex 32 > /etc/susu-phone-agent/phone_bridge_token.txt
chmod 600 /etc/susu-phone-agent/phone_bridge_token.txt
pip install fastapi uvicorn pydantic
# Edit bridge/bridge.py: set TOKEN_PATH to your token file path
uvicorn bridge.bridge:app --host 127.0.0.1 --port 7070
Expose it via nginx at /phone-bridge/ over HTTPS. See bridge/bridge.py for the full API.
pip install "mcp[cli]" fastmcp
# Edit mcp/phone_mcp.py: set TOKEN_PATH and BRIDGE_URL
Add to your Claude Code MCP config (~/.claude/mcp_config.json or similar):
{
"mcpServers": {
"phone": {
"type": "stdio",
"command": "python3",
"args": ["/path/to/mcp/phone_mcp.py"]
}
}
}
# Download Shizuku dependencies
mkdir -p android/libs
for artifact in api provider aidl shared; do
curl -o android/libs/shizuku-${artifact}.aar \
"https://repo1.maven.org/maven2/dev/rikka/shizuku/${artifact}/13.1.5/${artifact}-13.1.5.aar"
unzip -p android/libs/shizuku-${artifact}.aar classes.jar \
> android/libs/shizuku-${artifact}.jar
done
# Create a signing keystore (once)
keytool -genkeypair -keystore android/my.jks -alias susu \
-keyalg RSA -keysize 2048 -validity 10000
# Build (set KS, KS_PASS via environment)
export KS=android/my.jks
export KS_PASS=your_keystore_password
cd android && bash build.sh
Sideload android/output/susu-phone-agent.apk. On first launch:
✓ Token OKThe notification bar shows ● Connected · Idle when everything is linked.
Honor / MIUI / ColorOS users: Disable battery optimization for Phone Agent in system settings to prevent background killing. See the in-app prompts for your manufacturer's specific path.
The MCP exposes a small, allow-listed tool surface. There is no arbitrary executeShell tool. Package names passed to launch_app are validated against a strict regex before execution.
The Bridge token lives in Android's private app storage (getSharedPreferences). It is never written to logcat.
Note on Shizuku in wireless ADB mode: After a device reboot, Shizuku typically needs to be restarted from the Shizuku app. The Android Agent includes a boot receiver that re-registers the Shizuku listener automatically, but Shizuku itself must be re-initialized by the user (or by an ADB automation if you have a connected host). Full zero-touch reboot recovery requires rooted Shizuku.
An optional local rule engine. When enabled, the Agent polls a /sleep-guard/state endpoint every 4 seconds and presses HOME if the foreground app is on a blocked list — no model call, no AI inference.
Dual safety: Sleep Guard only activates when both are true:
guard_enabled = true in the app (opt-in, off by default)active: true in the server responseEither being false → no action. A server misconfiguration alone cannot lock the device.
{
"active": true,
"blocked_apps": ["com.example.app"],
"allow_pkg": "com.example.app",
"allow_until": 1756000000
}
input tap and input swipeinput text for keyboard inputIssues and pull requests welcome. Please do not include real tokens, private domains, or personal data in contributions.
What's different here: shell-level control via Shizuku instead of screenshot + vision, MCP-native instead of prompt-based, phone pulls jobs from your server instead of a model pushing commands, no AI inference on the device.
MIT — see LICENSE.
Android device bridge for Claude Code via MCP + Shizuku. No root, no model polling.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Susu Phone Agent 透過 stdio 在本機執行。
上次檢查時間:2026-10-26。 Android device bridge for Claude Code via MCP + Shizuku. No root, no model polling.