| name | AndroidUse MCP Secret |
| description | This skill should be used when the user asks to connect Codex to the AndroidUse Android MCP server, retrieve the AndroidUse MCP secret from an adb-connected device, refresh the secret with action.sh, configure ANDROIDUSE_MCP_SECRET, or set up adb forward for the androiduse MCP server. |
| version | 0.1.0 |
AndroidUse MCP Secret
Use this skill to connect Codex to the AndroidUse module MCP server running on a rooted Android device.
The AndroidUse MCP server is a streamable HTTP server exposed at:
http://127.0.0.1:8765/mcp
The server requires bearer-token authentication. Codex is configured with the MCP server name androiduse and reads the bearer token from:
ANDROIDUSE_MCP_SECRET
Never write the secret into Codex config, repo files, logs, commits, issue text, or final answers unless the user explicitly asks to display it.
Standard Workflow
- Confirm an adb device is connected:
adb devices
adb shell 'su -c "id"'
Accept root only when the output shows uid=0(root).
- Locate the active module directory.
Before reboot after install, KernelSU usually keeps the updated module at:
/data/adb/modules_update/AndroidUse
After reboot, the normal runtime path is:
/data/adb/modules/AndroidUse
Prefer modules_update when it exists and contains cli; otherwise use modules.
- Refresh the secret when the user asks for a new credential:
adb shell 'su -c "/data/adb/modules_update/AndroidUse/action.sh"'
or after reboot:
adb shell 'su -c "/data/adb/modules/AndroidUse/action.sh"'
action.sh creates or replaces:
.secret/mcp_secret
The directory and file must both be mode 700.
- Read the secret into the local shell environment:
export ANDROIDUSE_MCP_SECRET="$(adb shell 'su -c "cat /data/adb/modules_update/AndroidUse/.secret/mcp_secret"' | tr -d '\r')"
Use the rebooted path when appropriate:
export ANDROIDUSE_MCP_SECRET="$(adb shell 'su -c "cat /data/adb/modules/AndroidUse/.secret/mcp_secret"' | tr -d '\r')"
- Start the AndroidUse MCP server on the device if it is not already running:
adb shell 'su -c "/data/adb/modules_update/AndroidUse/cli mcp serve"'
The default listener is 127.0.0.1:8765. For normal development, keep this loopback-only and access it through adb forwarding.
The listener can be customized from the module env file:
/data/adb/modules_update/AndroidUse/.config/androiduse/mcp.env
or after reboot:
/data/adb/modules/AndroidUse/.config/androiduse/mcp.env
Supported keys:
ANDROIDUSE_MCP_HOST=127.0.0.1
ANDROIDUSE_MCP_PORT=8765
Use 0.0.0.0 or a LAN address only on trusted networks. Restart the MCP process after changing this file.
- Forward the device port to the workstation:
adb forward tcp:8765 tcp:8765
- Verify the endpoint:
curl -sS -i -H "Authorization: Bearer $ANDROIDUSE_MCP_SECRET" http://127.0.0.1:8765/mcp
Expect:
HTTP/1.1 200 OK
ok
Without the bearer token, expect 401 Unauthorized.
Codex MCP Configuration
The project uses a Codex MCP server entry named:
androiduse
Add it with the Codex CLI, not by manually editing config:
codex mcp add androiduse --url http://127.0.0.1:8765/mcp --bearer-token-env-var ANDROIDUSE_MCP_SECRET
Check it with:
codex mcp get androiduse
codex mcp list
Expected properties:
transport: streamable_http
url: http://127.0.0.1:8765/mcp
bearer_token_env_var: ANDROIDUSE_MCP_SECRET
Tool Surface
The AndroidUse MCP tool for shell execution is named:
mksh
mksh uses an automatically managed persistent PTY shell session keyed by the MCP HTTP session. Do not make the user manually provide a session id. Use reset: true when a fresh shell is needed, or stateless: true for a one-shot /system/bin/sh -c command.
Do not call the old tool name terminal_exec; it should return unknown tool.
A direct JSON-RPC smoke test:
curl -sS \
-H "Authorization: Bearer $ANDROIDUSE_MCP_SECRET" \
-H 'Content-Type: application/json' \
--data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mksh","arguments":{"command":"id; uname -m","timeout_secs":5}}}' \
http://127.0.0.1:8765/mcp
Expect root context and device architecture, for example uid=0(root) and aarch64.
The screenshot tool is named:
screenshot
It returns JSON text with source, mime_type, bytes, and data_base64. On modern devices /dev/graphics/fb0 may be missing, so the tool falls back to screencap -p.
Secure-window screenshots require the user to install and enable CaptureSposed separately:
https://github.com/99keshav99/CaptureSposed
Without CaptureSposed, FLAG_SECURE windows are expected to be blocked or hidden by Android's screenshot path.
For rooted-device DRM streaming app testing, liboemcrypto-disabler is an optional companion module, not a hard AndroidUse dependency:
https://github.com/Anonym0usWork1221/liboemcrypto-disabler
Cleanup
Stop a manually started test server by finding the process on the device:
adb shell 'su -c "ss -lntp 2>/dev/null | grep 8765 || true"'
adb shell 'su -c "kill <pid>"'
Remove forwarding:
adb forward --remove tcp:8765
Do not kill a service-managed process unless the user asked to stop the MCP server or the current task started it manually.
