Skip to content
Back to search

android-remote-control-mcp

An MCP Server for Android running on the phone, optmized for token usage, supports also files downloads and cloudflare and ngrok automated tunnelling.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/danielealbano/android-remote-control-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/danielealbano/android-remote-control-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/danielealbano--android-remote-control-mcp/badge.svg)](/listings/danielealbano--android-remote-control-mcp)

HTML

<a href="/listings/danielealbano--android-remote-control-mcp"><img src="/api/listings/danielealbano--android-remote-control-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Which build to download: GMS or FOSS

Each release provides two flavors of the APK — pick the one that matches your device:

- **GMS** (`…-gms-release.apk`) — the full build. **Requires Google Mobile Services (Google Play Services)** installed on the phone. Choose this on standard devices/emulators that ship with Google services. - **FOSS** (`…-foss-release.apk`) — a Google-free build with **no dependency on Google Mobile Services**. Works on **any** Android phone, including de-Googled ROMs and devices where Google services are unavailable.

If unsure, the GMS build is the right choice for a typical phone with the Play Store.

Option A: Download on your phone (easiest)

1. Open the [Releases](https://github.com/danielealbano/android-remote-control-mcp/releases) page on your phone's browser 2. Download the APK from the latest release 3. Open the downloaded APK and follow the prompts to install it (you may need to allow installation from unknown sources)

Option B: Download on your PC and install via ADB

1. Download the APK from the [Releases](https://github.com/danielealbano/android-remote-control-mcp/releases) page 2. Connect your phone via USB (with USB Debugging enabled) 3. Install the APK (use the GMS or FOSS file you downloaded):

adb install android-remote-control-mcp-<version>-gms-release.apk

Option C: Build from sources

git clone https://github.com/danielealbano/android-remote-control-mcp.git
cd android-remote-control-mcp
make build
make install  # installs on connected device/emulator

See [CONTRIBUTING.md](CONTRIBUTING.md) for full build requirements and instructions.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "android-remote-control-mcp",
  3. "description": "Android Remote Control MCP plugin marketplace",
  4. "owner": {
  5. "name": "Daniele Salvatore Albano",
  6. "email": "d.albano@gmail.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "android-remote-control",
  11. "description": "Channel plugin for Android Remote Control MCP — receives device events and pushes them into Claude Code sessions.",
  12. "source": "./channel-plugin",
  13. "category": "productivity"
  14. }
  15. ]
  16. }
README.md · README · 655 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/assets/arc-mcp-logo.png" alt="ARC MCP, Android Remote Control MCP" width="640">
  3. </p>
  4. # Android Remote Control MCP
  5. [![CI](https://github.com/danielealbano/android-remote-control-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/danielealbano/android-remote-control-mcp/actions/workflows/ci.yml)
  6. [![License: GPL v3 or later](https://img.shields.io/badge/License-GPLv3%2B-blue.svg)](LICENSE.md)
  7. [![Tunnel status](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fstatus.arc-tunnel.io%2Findex.json&query=%24.data.attributes.aggregate_state&label=tunnel&color=blue)](https://status.arc-tunnel.io/)
  8. An Android application that runs as an **MCP (Model Context Protocol) server**, enabling AI models to **fully control an Android device** remotely using accessibility services and screenshot capture.
  9. The app runs directly on your Android device (or emulator) and exposes an HTTP server (with optional HTTPS) implementing the MCP protocol. AI models like Claude can connect to it and interact with any app on the device: reading UI elements, tapping buttons, typing text, swiping, capturing screenshots, managing files, launching apps, and more.
  10. Optional [Privacy Mode](#privacy-mode) detects and hides personal data, such as emails, card numbers, credentials and names, in what the tools return, before it leaves the device for the AI provider. Detection runs entirely on the device. It reduces exposure, but cannot guarantee that nothing personal gets through.
  11. To reach the phone from anywhere, the free end-to-end encrypted HTTPS tunnel gives it a public URL with no account and no registration. TLS ends on the phone, so the tunnel service only relays encrypted bytes and cannot read your traffic. Cloudflare and ngrok are also supported, but they terminate TLS themselves and can read it.
  12. > **Warning:** This software is provided "as-is" without warranty of any kind, for **research and educational purposes only**. The authors do not condone the use of this tool for any illegal, unauthorized, or unethical activities. Users are solely responsible for ensuring their use complies with all applicable laws and regulations. By using this software, you agree to use it responsibly and at your own risk.
  13. > **Warning:** The free E2E HTTPS tunnel only works with the signed builds from this repository's [Releases](https://github.com/danielealbano/android-remote-control-mcp/releases); other builds are refused for security reasons.
  14. ---
  15. ## Contents
  16. - [Demo](#demo)
  17. - [Features](#features)
  18. - [Install](#install)
  19. - [Setup](#setup)
  20. - [Privacy Mode](#privacy-mode)
  21. - [Integrations](#integrations)
  22. - [Configuration](#configuration)
  23. - [Permissions Reference](#permissions-reference)
  24. - [Security](#security)
  25. - [Contributing](#contributing)
  26. - [License](#license)
  27. ---
  28. ## Demo
  29. <table>
  30. <tr>
  31. <td align="center" width="33%" valign="top">
  32. <a href="docs/assets/demo-reddit-post.gif" title="Click for full resolution"><img src="docs/assets/demo-reddit-post-small.gif" alt="Posting on Reddit through the MCP server" width="240"></a>
  33. <br><em>Posting on Reddit (sped up, ~6 min original)</em>
  34. </td>
  35. <td align="center" width="33%" valign="top">
  36. <a href="docs/assets/demo-install-booking.gif" title="Click for full resolution"><img src="docs/assets/demo-install-booking-small.gif" alt="Installing the booking.com app through the MCP server" width="240"></a>
  37. <br><em>Installing the booking.com app</em>
  38. </td>
  39. <td align="center" width="33%" valign="top">
  40. <a href="docs/assets/demo-flight-search.gif" title="Click for full resolution"><img src="docs/assets/demo-flight-search-small.gif" alt="Skyscanner flight search from Zurich to Istanbul through the MCP server" width="240"></a>
  41. <br><em>Flight search on Skyscanner, Zurich &rarr; Istanbul (sped up, ~4 min original)</em>
  42. </td>
  43. </tr>
  44. </table>
  45. <p align="center"><em>An AI model controlling an Android device through the MCP server &mdash; click any clip for full resolution.</em></p>
  46. ## Features
  47. ### MCP Server
  48. - HTTP server running directly on Android (Ktor + Netty), with optional HTTPS
  49. - Streamable HTTP transport at `/mcp` (MCP specification compliant, JSON-only, no SSE)
  50. - Combined authentication: static bearer token and/or a self-contained OAuth 2.1 server (Claude.ai / Claude Desktop custom connectors, with on-device approval)
  51. - Auto-generated self-signed TLS certificates (or custom certificate upload)
  52. - Configurable binding: localhost (127.0.0.1), network (0.0.0.0) or a specific IP address of the device
  53. - Auto-start on boot
  54. - Remote access tunnels via the free end-to-end encrypted tunnel (no account), Cloudflare Quick Tunnels or ngrok (public HTTPS URL)
  55. ### 65 MCP Tools across 15 Categories
  56. Screen introspection, system actions, touch actions, gestures, node actions, text input, utilities, file operations, app management, camera, intents, notifications, location, sharing, and shell.
  57. All tool names use the `android_` prefix by default (e.g., `android_tap`). When a device slug is configured (e.g., `pixel7`), the prefix becomes `android_pixel7_` (e.g., `android_pixel7_tap`).
  58. See [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) for the full tool reference with input/output schemas and examples.
  59. ### Android App
  60. - Material Design 3 UI with tabbed layout (Server / Settings / About) and dark mode
  61. - Server status monitoring (running/stopped) with permission warning banner
  62. - Connection info display (IP, port, token, tunnel URL)
  63. - Per-tool and per-parameter permissions (enable/disable individual MCP tools)
  64. - Permission management (Accessibility, Notifications, Camera, Microphone)
  65. - Remote access tunnel configuration (free E2E tunnel / Cloudflare / ngrok)
  66. - Storage location management (automatic locations + SAF authorization for file tools)
  67. - Server log viewer (MCP tool calls, tunnel events)
  68. - Headless setup via ADB (configure, grant permissions, start/stop server without UI)
  69. ### Comparison with Alternatives
  70. | Feature | This project | [mobile-mcp] | [Android-MCP] | [android-mcp-server] | [adb-mcp] | [droidrun-mcp] |
  71. |---------|:-:|:-:|:-:|:-:|:-:|:-:|
  72. | MCP tools | 65 | 21 | 11 | 5 | 10 | 11 |
  73. | Runs on the phone (no ADB) | :white_check_mark: | :x: | :x: | :x: | :x: | :x: |
  74. | Action latency | 10-100 ms | 1-4 s | 1-4 s | 1-4 s | 1-4 s | 1-4 s |
  75. | Works over the internet | :white_check_mark: | :x: | :x: | :x: | :x: | :x: |
  76. | Token-efficient screen state | :white_check_mark: | :x: | :white_check_mark: | :x: | :x: | :white_check_mark: |
  77. | Annotated screenshots | :white_check_mark: | :x: | :white_check_mark: | :x: | :x: | :x: |
  78. | Configurable screenshot resolution/quality | :white_check_mark: | :x: | :x: | :x: | :x: | :x: |
  79. | Per-tool enable/disable | :white_check_mark: | :x: | :x: | :x: | :x: | :x: |
  80. | Multi-device support | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | :x: |
  81. | Camera, clipboard, files, downloads | :white_check_mark: | :x: | :x: | :x: | :x: | :x: |
  82. | iOS support | :x: | :white_check_mark: | :x: | :x: | :x: | :x: |
  83. [mobile-mcp]: https://github.com/mobile-next/mobile-mcp
  84. [Android-MCP]: https://github.com/CursorTouch/Android-MCP
  85. [android-mcp-server]: https://github.com/minhalvp/android-mcp-server
  86. [adb-mcp]: https://github.com/srmorete/adb-mcp
  87. [droidrun-mcp]: https://github.com/chukfinley/droidrun-mcp-server
  88. Most alternatives rely on ADB running on a host machine, which means a USB cable or local network connection and a computer sitting next to the phone. This project runs entirely on the device itself, so you can expose the MCP endpoint through a tunnel and control your phone from anywhere.
  89. On the token efficiency side, ADB-based tools typically return raw `uiautomator` XML dumps which can easily be 10-50x more verbose than the compact representation used here. Combined with numbered screenshot annotations, configurable image quality, and the ability to disable tools you don't need (every tool definition costs tokens on every turn), this significantly reduces the per-interaction cost in agentic loops.
  90. ---
  91. ## Install
  92. ### Which build to download: GMS or FOSS
  93. Each release provides two flavors of the APK — pick the one that matches your device:
  94. - **GMS** (`…-gms-release.apk`) — the full build. **Requires Google Mobile Services (Google Play Services)** installed on the phone. Choose this on standard devices/emulators that ship with Google services.
  95. - **FOSS** (`…-foss-release.apk`) — a Google-free build with **no dependency on Google Mobile Services**. Works on **any** Android phone, including de-Googled ROMs and devices where Google services are unavailable.
  96. If unsure, the GMS build is the right choice for a typical phone with the Play Store.
  97. ### Option A: Download on your phone (easiest)
  98. 1. Open the [Releases](https://github.com/danielealbano/android-remote-control-mcp/releases) page on your phone's browser
  99. 2. Download the APK from the latest release
  100. 3. Open the downloaded APK and follow the prompts to install it (you may need to allow installation from unknown sources)
  101. ### Option B: Download on your PC and install via ADB
  102. 1. Download the APK from the [Releases](https://github.com/danielealbano/android-remote-control-mcp/releases) page
  103. 2. Connect your phone via USB (with USB Debugging enabled)
  104. 3. Install the APK (use the GMS or FOSS file you downloaded):
  105. ```bash
  106. adb install android-remote-control-mcp-<version>-gms-release.apk
  107. ```
  108. ### Option C: Build from sources
  109. ```bash
  110. git clone https://github.com/danielealbano/android-remote-control-mcp.git
  111. cd android-remote-control-mcp
  112. make build
  113. make install # installs on connected device/emulator
  114. ```
  115. See [CONTRIBUTING.md](CONTRIBUTING.md) for full build requirements and instructions.
  116. ---
  117. ## Setup
  118. 1. **Open the app.** The Server tab shows a permission warning banner; grant permissions from there or via Settings > Permissions.
  119. 2. **Grant permissions:**
  120. - **Accessibility Service** — **required.** Powers UI introspection, action execution, and screenshots; nothing works without it.
  121. - **If the toggle is greyed out** (Android 13+, common on Samsung/One UI for apps installed from an APK): this is Android's "Restricted settings" protection. A dialog reads *"Restricted setting — For your security, this setting is currently unavailable."* To unblock it, go to **Settings → Apps → Android Remote Control MCP → App info**, tap the **⋮ menu** (top-right), choose **Allow restricted settings**, confirm with your PIN/pattern/biometric, then enable the Accessibility Service. (Play Store / F-Droid installs are not affected.)
  122. - **Notifications** — **optional** (recommended for OAuth). OAuth sign-in approvals (Claude.ai / Claude Desktop, ChatGPT, or any third-party OAuth client) arrive as heads-up notifications you tap to confirm the 2-digit code and approve. It is **no longer required** for OAuth login, though: if you don't grant this permission, pending requests still appear as a **card on the app's Server screen** that you tap to review and approve/deny. The **Event Channel** push feature — e.g. pushing device events to Claude Code — runs as a foreground service that posts its status notification through this permission on Android 13+.
  123. - **Other permissions** (optional) — Camera, Microphone, and Location enable their corresponding MCP tools. The app works without them; only the dependent features are disabled until granted. See the [Permissions Reference](#permissions-reference) below for the complete list.
  124. - **Storage locations** — configure in Settings > Storage if you plan to use the file tools (automatic locations like Downloads, plus custom locations via SAF).
  125. 3. **Start the server.** Go back to the **Server tab** and tap **Start**.
  126. The server starts on `http://127.0.0.1:8080` by default. The connection info (IP, port, token, URL) is displayed on the Server tab.
  127. > **Note**: `127.0.0.1` refers to the phone's localhost, not your computer. To connect from your computer, use [adb port forwarding](#using-with-adb-port-forwarding), bind to `0.0.0.0` (network mode), or enable a [remote access tunnel](#using-remote-access-tunnels).
  128. ---
  129. ## Privacy Mode
  130. Privacy Mode detects and hides personal data — emails, credit cards and IBANs, credentials, phone
  131. numbers, national IDs, addresses, and names — in everything the MCP tools return (screen content,
  132. notifications, clipboard, files, …) **before it leaves the device** for the AI provider. Detection
  133. runs fully on-device: fast rule-based checks (checksums, formats, field context) combined with a
  134. local NER model — no cloud calls. Detected values are either pseudonymized with consistent
  135. placeholders (`EMAIL#a1b2c`, so AI tools keep working across screens) or fully redacted. Detection
  136. is best-effort mitigation, not a guarantee.
  137. Shell tools are not covered: commands and their output pass through unchanged.
  138. The model is the [Ai4Privacy multilingual anonymiser](https://huggingface.co/ai4privacy/llama-ai4privacy-multilingual-categorical-anonymiser-openpii)
  139. (MIT license, Built with Llama), downloaded once on first enable (~150 MB) directly from the pinned
  140. Hugging Face revision and checksum-verified on device.
  141. ### Measured detection rates
  142. Share of personal data items detected per category by the full pipeline, measured with the in-repo
  143. effectiveness benchmark (`make privacy-benchmark`) on realistic UI-style content across 8 languages:
  144. | Category | Detected |
  145. |---|---|
  146. | Addresses | 77.9% |
  147. | Cards & IBANs | 75.3% |
  148. | Credentials | 90.9% |
  149. | Emails | 100.0% |
  150. | Names | 0.8% |
  151. | National IDs | 93.0% |
  152. | Phone numbers | 84.4% |
  153. Names are the on-device model's known weak spot (it recognizes common Western names far better than
  154. the globally diverse names in the benchmark); improving name detection with a fine-tuned model is on
  155. the roadmap. Actual results vary with content and language.
  156. ### Enabling Privacy Mode
  157. - **From the main Server screen**: tap **Set up Privacy Mode** on the Privacy Mode card (shown while
  158. the mode is off).
  159. - **Or via Settings → Privacy**: turn on **Enable Privacy Mode** and confirm the one-time model
  160. download. After the download and warm-up, a short on-device benchmark measures the expected
  161. per-screen overhead and shows it on the same screen.
  162. - Protected categories, pseudonymize-vs-redact, and the placeholder format are configurable in
  163. **Settings → Privacy**.
  164. ---
  165. ## Integrations
  166. ### Claude Desktop / Claude Code
  167. Add the server to your `.mcp.json` configuration file:
  168. ```json
  169. {
  170. "mcpServers": {
  171. "android-phone": {
  172. "type": "http",
  173. "url": "http://DEVICE_IP:PORT/mcp",
  174. "headers": {
  175. "Authorization": "Bearer YOUR_TOKEN"
  176. }
  177. }
  178. }
  179. }
  180. ```
  181. Replace `DEVICE_IP`, `PORT`, and `YOUR_TOKEN` with the values shown in the app's Server tab. If the server is bound to localhost (default), you'll need [adb port forwarding](#using-with-adb-port-forwarding) or a [remote access tunnel](#using-remote-access-tunnels) to connect.
  182. > **Note for clients without custom-header support:** if your MCP client cannot send an `Authorization` header and does not support OAuth, you can turn off both auth methods in the app (**Settings → Access** — disable Bearer token and OAuth). The app warns and asks you to confirm, because the server is then **open**: anyone who can reach it has full control. Only do this on a network you trust.
  183. ### Connect from Claude.ai & Claude Desktop (Custom Connector, OAuth)
  184. Claude.ai (web) and Claude Desktop connect as a **custom connector** (remote MCP) using OAuth 2.1 — the app is its own OAuth Authorization Server, so no external account or pre-registration is needed. This requires the server to be reachable over a **public HTTPS URL**, so you must first enable a [remote access tunnel](#using-remote-access-tunnels) — a `localhost`/LAN address or `adb` port-forward will **not** work.
  185. 1. **OAuth is enabled by default** — no action needed (if you previously disabled it, re-enable it under **Settings → Access**). The bearer token stays enabled too; both are accepted.
  186. 2. Open **Settings → Tunnel**, enable **Remote Access** (the default free E2E tunnel needs no account; the first setup takes about 10–30 seconds), and start the server. Copy the public `https://…` URL from the Server tab and append `/mcp` (e.g. `https://<name>.d.arc-tunnel.io/mcp`).
  187. 3. In Claude, open **[Customize → Connectors → Add custom connector](https://claude.ai/customize/connectors?modal=add-custom-connector)**, paste the `https://…/mcp` URL, and **leave the OAuth Client ID and Client Secret blank** (the app uses Dynamic Client Registration). Click **Add**.
  188. 4. Claude opens a browser approval page showing a **2-digit code**. On the device, tap the heads-up notification — or, if the Notifications permission is off, open the app's **Server** screen and tap the **pending approvals** card — to open the approval screen, confirm the code matches, and **Approve**.
  189. 5. Manage or revoke connected clients any time under **Settings → Access → Connected clients**. Revoking immediately invalidates that client's tokens.
  190. > **Public URL override (optional):** if your tunnel/host topology needs a fixed public host (or you bind to `0.0.0.0` without a trusted proxy), set a **Public URL override** in Settings → Access so OAuth metadata and links use a stable host.
  191. Custom connectors are available on the Free (1 connector), Pro, Max, Team, and Enterprise plans (currently in beta).
  192. > ⚠️ **Security:** treat the public tunnel URL as sensitive, approve only connections you initiated (verify the 2-digit code), revoke clients you no longer use, and stop the tunnel and server when you are done. Never point it at a device holding sensitive data.
  193. ### Connect from ChatGPT (Custom Connector, OAuth)
  194. ChatGPT connects to the server as a **custom MCP connector** using the same self-contained OAuth 2.1 flow. As with Claude, the server must be reachable over a **public HTTPS URL**, so enable a [remote access tunnel](#using-remote-access-tunnels) first — a `localhost`/LAN address or `adb` port-forward will **not** work. Custom connectors require a paid plan (Plus, Pro, Business, Enterprise, or Edu — not Free) and are set up from the **ChatGPT web app**.
  195. 1. **Enable Developer mode** — in ChatGPT on the web, open **Settings → Connectors → Advanced settings** (labelled **Apps & Connectors** on some builds) and turn on **Developer mode**.
  196. 2. **Start the tunnel** — same as the Claude flow above: OAuth stays enabled by default, turn on **Remote Access** under Settings → Tunnel, start the server, and copy the public `https://…/mcp` URL from the Server tab.
  197. 3. **Add the connector** — open **Settings → Connectors → Create**, give it a name and description, paste the `https://…/mcp` URL, select **OAuth** as the authentication method, and leave any Client ID / Client Secret blank (the app self-registers clients via Dynamic Client Registration).
  198. 4. **Approve on the device** — ChatGPT starts the OAuth flow. Tap the heads-up notification — or, if the Notifications permission is off, open the app's **Server** screen and tap the **pending approvals** card — confirm the 2-digit code matches, and **Approve** (identical to the Claude approval step).
  199. 5. Manage or revoke the connected client any time under **Settings → Access → Connected clients** in the app.
  200. > ⚠️ **Security:** the same cautions apply — treat the tunnel URL as sensitive, approve only connections you initiated (verify the code), revoke unused clients, and stop the tunnel and server when you are done.
  201. ### Other MCP Clients
  202. The MCP server exposes a standard Streamable HTTP endpoint at `/mcp` with combined authentication (static bearer token and/or OAuth 2.1). Any MCP-compatible client can connect to it — refer to your client's documentation for the specific configuration format.
  203. ### Testing with MCP Inspector
  204. [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the official visual testing tool for MCP servers. It provides a browser-based UI to connect, list tools, fill parameters, and see responses:
  205. ```bash
  206. npx @modelcontextprotocol/inspector
  207. ```
  208. This opens a UI at `http://localhost:6274` where you can connect to your server and test tools interactively.
  209. ### Testing with curl
  210. All requests are sent as JSON-RPC 2.0 via `POST /mcp` (Streamable HTTP transport). The server is stateless: every request stands alone, so there is no session to open and no `mcp-session-id` to send, and tools can be called directly:
  211. ```bash
  212. # List available tools
  213. curl -X POST http://localhost:8080/mcp \
  214. -H "Authorization: Bearer YOUR_TOKEN" \
  215. -H "Content-Type: application/json" \
  216. -H "Accept: application/json, text/event-stream" \
  217. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  218. # Get the current screen state (UI nodes + optional screenshot)
  219. curl -X POST http://localhost:8080/mcp \
  220. -H "Authorization: Bearer YOUR_TOKEN" \
  221. -H "Content-Type: application/json" \
  222. -H "Accept: application/json, text/event-stream" \
  223. -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"android_get_screen_state","arguments":{}}}'
  224. # Tap at coordinates
  225. curl -X POST http://localhost:8080/mcp \
  226. -H "Authorization: Bearer YOUR_TOKEN" \
  227. -H "Content-Type: application/json" \
  228. -H "Accept: application/json, text/event-stream" \
  229. -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"android_tap","arguments":{"x":540,"y":1200}}}'
  230. ```
  231. The bearer token is shown in the app's connection info and can be copied directly. Bearer authentication is controlled by the **Bearer token** toggle in **Settings → Access** (not by clearing the value): with it enabled, every `/mcp` request must present the token (or a valid OAuth access token). The server accepts unauthenticated requests only when **both** the Bearer token and OAuth are disabled.
  232. ---
  233. ## Configuration
  234. ### Server Settings (via App UI)
  235. | Setting | Default | Description |
  236. |---------|---------|-------------|
  237. | Port | `8080` | HTTP/HTTPS server port |
  238. | Binding Address | `127.0.0.1` | `127.0.0.1` (localhost, use with adb port forwarding), `0.0.0.0` (network, all interfaces) or a specific IP address of the device (IPv4 or IPv6, not IPv6 link-local, without a zone index such as `%3`; the server does not start while the device does not have it) |
  239. | Bearer Token | Enabled, auto-generated UUID | Static token for MCP requests (Settings → Access). Enforcement is set by the Bearer toggle, not by clearing the value. |
  240. | OAuth | Enabled | Self-contained OAuth 2.1 server for Claude.ai / Claude Desktop custom connectors (Settings → Access). |
  241. | Public URL override | Empty (auto-detect) | Pin the public host used for OAuth metadata and share links. |
  242. | HTTPS | Disabled | Enable HTTPS with auto-generated self-signed certificate (configurable hostname) or upload custom .p12/.pfx |
  243. | Auto-start on Boot | Disabled | Start MCP server automatically when device boots |
  244. | Device Slug | Empty | Optional device identifier for tool name prefix (e.g., `pixel7` makes tools `android_pixel7_tap`) |
  245. | Remote Access Tunnel | Disabled | Expose server via public HTTPS URL (free E2E tunnel by default; Cloudflare Quick Tunnels or ngrok) |
  246. | Tunnel Local Port | The server port on installs from before this setting (unless their HTTPS kept their Cloudflare/ngrok tunnel off), a random port of 61000-65535 otherwise | The port Cloudflare and ngrok forward to (`http://localhost:<port>`). When the server serves plain HTTP on `127.0.0.1` on that same port (Localhost, Network, or the Specific IP 127.0.0.1), the tunnel uses it; otherwise the server opens a plain HTTP listener of its own on `127.0.0.1:<port>`, with the same authentication. With HTTPS on and such a binding, choose a port other than the server port |
  247. | Tool Permissions | All enabled | Per-tool and per-parameter enable/disable (Settings > MCP Tools) |
  248. | File Size Limit | 50 MB | Maximum file size for file operations (range 1-500 MB) |
  249. | Allow HTTP Downloads | Disabled | Allow non-HTTPS downloads via `android_download_from_url` |
  250. | Allow Unverified HTTPS | Disabled | Accept unverified (self-signed or invalid) HTTPS certificates for `android_download_from_url` (less secure) |
  251. | Block Local Network Downloads | Disabled | `android_download_from_url` refuses to connect to this phone, the local network or VPN addresses (loopback, unspecified, private LAN, link-local, CGNAT/Tailscale and IPv6 unique-local addresses, including their IPv4-mapped/compatible IPv6 forms) |
  252. | Download Timeout | 60 seconds | Timeout for file downloads (range 10-300 seconds) |
  253. | Shell: Allow Elevated Commands | Disabled | Lets MCP clients ask to run single shell commands through Shizuku (as the adb shell user, or as root when Shizuku runs as root) or `su` (as root). Every shell setting is in Settings → Shell and applies at once, also while the server runs |
  254. | Shell: Auto-allow Elevation | Disabled | Run every elevated command without asking (the blocklist still applies) |
  255. | Shell: Blocklist | Empty | Commands matching a pattern are always refused, elevated or not (a pattern matches the whole command, `*` matches anything: `*reboot*`). It compares text only, so the same action written another way is not refused |
  256. | Shell: Allowlist | Empty | Elevated commands matching a pattern run without asking while auto-allow is off (a pattern matches the whole command; `*` never matches `;`, `&`, `\|`, `` ` ``, `$`, `(`, `)`, `<`, `>` or a line break); any other elevated command asks for approval on the phone. Environment variables sent with the command (`envs`) are not checked |
  257. | Shell: Maximum Running Processes | 16 | Range 1-64. Android can stop child processes of apps when more than 32 run on the device; a normal command stopped this way ends with exit code 137 and no other notice. |
  258. | Shell: Finished Processes Kept | 32 | Range 0-256 |
  259. | Shell: Background Timeout, Default | 30 minutes | From 1 minute up to the maximum |
  260. | Shell: Background Timeout, Maximum | 120 minutes | Range 1-1440 minutes, not below the default |
  261. | Shell: Approval Timeout | 60 seconds | Range 10-85 seconds |
  262. | Shell: Foreground Wait Limit | 90 seconds | Range 10-90 seconds; `android_shell_exec` waits at most this long, then the command continues in the background |
  263. | Shell: Output per Call | 64 KiB | Range 4-256 KiB |
  264. | Shell: Output Kept per Process | 1024 KiB | Range 64-16384 KiB; beyond it only the start and the end of the output are kept. It is held in the app's memory for every running and every kept finished process: (running + kept) × output kept per process must not exceed 64 MiB, and a change that would go over it is refused |
  265. ### Using with adb Port Forwarding
  266. When the server is bound to `127.0.0.1` (default, most secure):
  267. ```bash
  268. # Forward device port to host
  269. adb forward tcp:8080 tcp:8080
  270. # Test connection from host
  271. curl -X POST http://localhost:8080/mcp \
  272. -H "Authorization: Bearer YOUR_TOKEN" \
  273. -H "Content-Type: application/json" \
  274. -H "Accept: application/json, text/event-stream" \
  275. -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
  276. ```
  277. ### Using over Network
  278. When the server is bound to `0.0.0.0`:
  279. 1. Find the device's IP address (shown in the app's connection info)
  280. 2. Connect directly via `POST http://DEVICE_IP:8080/mcp` with bearer token
  281. **Warning**: Binding to `0.0.0.0` exposes the server to all devices on the same network. Only use on trusted private networks.
  282. To listen on one address only (the device's address on a VPN such as Tailscale, for example), choose **Specific IP** and enter an IP address of the device: the server listens on that address alone (plus `127.0.0.1` when a tunnel is enabled, for the tunnel), so normally only the network of that address reaches it, and does not start while the device does not have it.
  283. ### Using Remote Access Tunnels
  284. For connecting from outside the local network without port forwarding:
  285. 1. **Free E2E tunnel** (default, no account required): end-to-end encrypted. The phone enrolls with hardware key attestation, gets a name under `d.arc-tunnel.io` and a public certificate (Let's Encrypt, Google Trust Services or ZeroSSL) issued to its own key, and terminates TLS itself — the tunnel service only relays ciphertext (unlike Cloudflare or ngrok, which read the traffic). The refresh icon next to the URL re-enrolls under a new name. A Certificate Transparency check (on by default) warns if a certificate for your name is ever issued to another key. A status check (on by default) reads the public status page at most every 30 minutes while the server is running or the Server screen is open, and warns, on the Server screen and with a notification, when the service reports a problem. Self-hosters change the base address. Self-hosting needs tunneld 0.8.0 or later.
  286. 2. **Cloudflare Quick Tunnels** (no account required): Creates a temporary tunnel with a random `*.trycloudflare.com` HTTPS URL.
  287. 3. **ngrok** (account required): Supports optional custom domains. Requires an ngrok authtoken (free tier available). Available on arm64-v8a and x86_64 devices.
  288. Cloudflare and ngrok forward to `http://localhost:<tunnel local port>` (Settings → Tunnel), so they also work while the server serves HTTPS: the server then gives them a plain HTTP listener of its own on `127.0.0.1`.
  289. Enable the tunnel in the app's "Remote Access" section. The public URL is displayed in the connection info and server logs.
  290. ### Headless Setup via ADB
  291. The app can be fully configured and controlled from the command line without opening the UI. This is useful for automated setups, CI pipelines, or headless devices.
  292. Replace `<app-id>` with the application ID for your build:
  293. - **Debug (gms flavor)**: `com.danielealbano.androidremotecontrolmcp.gms.debug`
  294. - **Debug (foss flavor)**: `com.danielealbano.androidremotecontrolmcp.foss.debug`
  295. - **Release (both flavors)**: `com.danielealbano.androidremotecontrolmcp`
  296. #### Grant Permissions
  297. ```bash
  298. # Enable Accessibility Service (required for UI introspection, actions, and screenshots)
  299. adb shell settings put secure enabled_accessibility_services \
  300. <app-id>/com.danielealbano.androidremotecontrolmcp.services.accessibility.McpAccessibilityService
  301. # Enable Notification Listener Service (required for notification tools)
  302. adb shell cmd notification allow_listener \
  303. <app-id>/com.danielealbano.androidremotecontrolmcp.services.notifications.McpNotificationListenerService
  304. # Grant notification permission (Android 13+)
  305. adb shell pm grant <app-id> android.permission.POST_NOTIFICATIONS
  306. # Grant camera permission
  307. adb shell pm grant <app-id> android.permission.CAMERA
  308. # Grant microphone permission
  309. adb shell pm grant <app-id> android.permission.RECORD_AUDIO
  310. # Grant location permissions
  311. adb shell pm grant <app-id> android.permission.ACCESS_FINE_LOCATION
  312. adb shell pm grant <app-id> android.permission.ACCESS_COARSE_LOCATION
  313. adb shell pm grant <app-id> android.permission.ACCESS_BACKGROUND_LOCATION
  314. # Grant nearby WiFi devices permission (Android 13+)
  315. adb shell pm grant <app-id> android.permission.NEARBY_WIFI_DEVICES
  316. # Grant media read permissions (Android 13+)
  317. adb shell pm grant <app-id> android.permission.READ_MEDIA_IMAGES
  318. adb shell pm grant <app-id> android.permission.READ_MEDIA_VIDEO
  319. adb shell pm grant <app-id> android.permission.READ_MEDIA_AUDIO
  320. ```
  321. See [docs/PERMISSIONS.md](docs/PERMISSIONS.md) for the full reference and a copy-paste script that grants everything in one go.
  322. #### Configure the App
  323. All extras are optional — only the ones provided are updated. The app does **not** need to be open.
  324. > **Requires adb.** The configuration receiver and the service trampoline are gated on
  325. > `android.permission.DUMP`, which the adb shell UID holds but ordinary apps cannot obtain. The
  326. > commands below work unchanged from `adb shell`; an app on the device cannot use them to
  327. > reconfigure the server. See the [Security](#security) section.
  328. ```bash
  329. adb shell am broadcast \
  330. -a com.danielealbano.androidremotecontrolmcp.ADB_CONFIGURE \
  331. -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbConfigReceiver \
  332. --es bearer_token "my-secret-token" \
  333. --es binding_address "0.0.0.0" \
  334. --ei port 8080 \
  335. --ez auto_start_on_boot true \
  336. --ez hide_from_recents false \
  337. --ez https_enabled false \
  338. --es certificate_source "AUTO_GENERATED" \
  339. --es certificate_hostname "mcp.local" \
  340. --ez tunnel_enabled true \
  341. --es tunnel_provider "android-remote-control-mcp-tunneld" \
  342. --es arc_tunnel_base_address "arc-tunnel.io" \
  343. --ez arc_tunnel_ct_check_enabled true \
  344. --ez arc_tunnel_status_check_enabled true \
  345. --es cloudflare_tunnel_mode "TOKEN" \
  346. --es cloudflare_tunnel_token "your-cloudflare-tunnel-token" \
  347. --es cloudflare_tunnel_extra_args "--edge region1.v2.argotunnel.com:7844" \
  348. --es ngrok_authtoken "your-ngrok-token" \
  349. --es ngrok_domain "your-domain.ngrok-free.app" \
  350. --ei tunnel_local_port 61200 \
  351. --ei file_size_limit_mb 50 \
  352. --ez allow_http_downloads false \
  353. --ez allow_unverified_https_certs false \
  354. --ez block_local_network_downloads false \
  355. --ei download_timeout_seconds 60 \
  356. --es device_slug "pixel8" \
  357. --es tool_permissions '{"disabled_tools":["tap"],"disabled_params":{"swipe":["duration_ms"]}}'
  358. ```
  359. ```bash
  360. # Disable bearer authentication (use only on trusted networks; the server is open
  361. # only if OAuth is also disabled — see the Security section)
  362. adb shell am broadcast \
  363. -a com.danielealbano.androidremotecontrolmcp.ADB_CONFIGURE \
  364. -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbConfigReceiver \
  365. --ez bearer_token_enabled false
  366. ```
  367. Bearer enforcement is controlled by `--ez bearer_token_enabled <bool>`, NOT by clearing the value. Clearing the value (`--es bearer_token ""`) while `bearer_token_enabled=true` makes `/mcp` fail CLOSED (401) — it does NOT open the server. The server accepts unauthenticated requests only when BOTH `bearer_token_enabled` and `oauth_enabled` are false.
  368. | Extra | Type | Description |
  369. |-------|------|-------------|
  370. | `bearer_token` | string | Static bearer-token value (clearing it while `bearer_token_enabled=true` fails closed, it does NOT disable auth) |
  371. | `bearer_token_enabled` | boolean | Enable/disable bearer-token authentication (controls enforcement, independent of the value) |
  372. | `oauth_enabled` | boolean | Enable/disable the self-contained OAuth 2.1 server (Claude.ai / Claude Desktop connectors) |
  373. | `public_url_override` | string | Pin the public host used for OAuth metadata and share links (empty = auto-detect from the request) |
  374. | `binding_address` | string | `127.0.0.1` (localhost), `0.0.0.0` (network) or another IP address literal of the device (specific IP) |
  375. | `port` | int | HTTP/HTTPS server port (1-65535) |
  376. | `auto_start_on_boot` | boolean | Start MCP server when device boots |
  377. | `hide_from_recents` | boolean | Exclude the app from the Android Recent Tasks list |
  378. | `https_enabled` | boolean | Enable HTTPS with TLS |
  379. | `certificate_source` | string | `AUTO_GENERATED` or `CUSTOM` |
  380. | `certificate_hostname` | string | Hostname for auto-generated certificate |
  381. | `tunnel_enabled` | boolean | Enable remote access tunnel |
  382. | `tunnel_provider` | string | `android-remote-control-mcp-tunneld` (free E2E tunnel), `CLOUDFLARE` or `NGROK` |
  383. | `arc_tunnel_base_address` | string | Base address of the free E2E tunnel service (default `arc-tunnel.io`; hosts `enroll.`, `connect.` and `d.` are derived) |
  384. | `arc_tunnel_ct_check_enabled` | boolean | Certificate Transparency check for the free E2E tunnel (default `true`) |
  385. | `arc_tunnel_status_check_enabled` | boolean | Status check of the public free E2E tunnel service, with the tunnel on, at most every 30 minutes while the server is running or the Server screen is open (default `true`) |
  386. | `arc_tunnel_enroll` | boolean | `true` enrolls the free E2E tunnel (or resumes a failed certificate issuance) with the settings in the same broadcast, while the app is visible and the server is stopped; headless, use the trampoline action `enroll-tunnel` below. The public URL appears in the Server tab |
  387. | `cloudflare_tunnel_mode` | string | `FREE` (Quick Tunnel, random `*.trycloudflare.com` URL) or `TOKEN` (named tunnel with static hostname) |
  388. | `cloudflare_tunnel_token` | string | Cloudflare named-tunnel token (used when `cloudflare_tunnel_mode` is `TOKEN`) |
  389. | `cloudflare_tunnel_extra_args` | string | Optional extra arguments passed to cloudflared (e.g. `--edge region1.v2.argotunnel.com:7844`) |
  390. | `ngrok_authtoken` | string | ngrok authentication token |
  391. | `ngrok_domain` | string | ngrok custom domain (optional) |
  392. | `tunnel_local_port` | int | Port Cloudflare and ngrok forward to on `localhost` (1-65535) |
  393. | `file_size_limit_mb` | int | Max file size for file operations (1-500) |
  394. | `allow_http_downloads` | boolean | Allow non-HTTPS downloads |
  395. | `allow_unverified_https_certs` | boolean | Allow unverified HTTPS certificates for downloads |
  396. | `block_local_network_downloads` | boolean | Refuse downloads from this phone, the local network and VPN addresses |
  397. | `download_timeout_seconds` | int | Download timeout (10-300) |
  398. | `device_slug` | string | Device identifier for tool name prefix |
  399. | `tool_permissions` | string (JSON) | Per-tool and per-parameter permissions: `{"disabled_tools":["tool_name"],"disabled_params":{"tool_name":["param"]}}` |
  400. | `storage_location_id` | string | ID of an existing storage location (from `android_list_storage_locations` or Settings > Storage); required by the two extras below, unknown IDs are ignored |
  401. | `storage_allow_write` | boolean | Allow write operations on the location identified by `storage_location_id` |
  402. | `storage_allow_delete` | boolean | Allow delete operations on the location identified by `storage_location_id` |
  403. | `shell_elevation_enabled` | boolean | Allow elevated shell commands |
  404. | `shell_auto_allow_elevation` | boolean | Run every elevated shell command without asking |
  405. | `shell_blocklist` | string (JSON) | Shell blocklist as a JSON array of patterns, e.g. `["*reboot*"]` (`[]` empties it; invalid JSON is ignored) |
  406. | `shell_allowlist` | string (JSON) | Shell allowlist as a JSON array of patterns (`[]` empties it; invalid JSON is ignored) |
  407. | `shell_max_running_processes` | int | Maximum running shell processes (1-64; (running + kept) × output kept per process at most 64 MiB) |
  408. | `shell_max_finished_processes` | int | Finished shell processes kept (0-256; (running + kept) × output kept per process at most 64 MiB) |
  409. | `shell_background_timeout_default_minutes` | int | Default background timeout in minutes (1 up to the maximum) |
  410. | `shell_background_timeout_max_minutes` | int | Maximum background timeout in minutes (1-1440, not below the default; both can be sent in one broadcast) |
  411. | `shell_approval_timeout_seconds` | int | Approval timeout in seconds (10-85) |
  412. | `shell_foreground_wait_seconds` | int | Foreground wait limit in seconds (10-90) |
  413. | `shell_output_per_call_kib` | int | Output returned per call in KiB (4-256) |
  414. | `shell_output_buffer_kib` | int | Output kept per process in KiB (64-16384; (running + kept) × output kept per process at most 64 MiB; limits sent in one broadcast can be in any order) |
  415. #### Start the MCP Server
  416. The server must be started via a trampoline Activity (required on Android 12+ to gain foreground service exemption). This works even when the app is force-stopped.
  417. ```bash
  418. adb shell am start \
  419. -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbServiceTrampolineActivity \
  420. --es action start
  421. ```
  422. #### Stop the MCP Server
  423. ```bash
  424. adb shell am start \
  425. -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbServiceTrampolineActivity \
  426. --es action stop
  427. ```
  428. #### Enroll the Free E2E Tunnel
  429. Enrollment (getting the device's name and certificate) runs in a short foreground service. Headless, use the same trampoline Activity as for starting the server; it also resumes a failed certificate issuance. Run it while the server is stopped.
  430. ```bash
  431. adb shell am start \
  432. -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbServiceTrampolineActivity \
  433. --es action enroll-tunnel
  434. ```
  435. `--ez arc_tunnel_enroll true` on the configuration broadcast does the same when the app is visible; from the background Android 12+ refuses the foreground service start and the app reports "background start refused".
  436. ---
  437. ## Permissions Reference
  438. The app declares the permissions below. **Normal** permissions are granted automatically at install. **Runtime** permissions and **Special access** require explicit user action (via the app's Settings > Permissions tab, or programmatically — see [Granting Permissions Programmatically](docs/PERMISSIONS.md)). All runtime permissions are optional: the app works without them, but the features that depend on them are disabled until granted. The optional Shizuku permission for elevated shell commands is granted in Settings → Shell (Grant access) or in the Shizuku app.
  439. | Permission | Type | Used for |
  440. |------------|------|----------|
  441. | `INTERNET` | Normal | HTTP/HTTPS server and remote access tunnels |
  442. | `ACCESS_NETWORK_STATE` | Normal | Detect network connectivity |
  443. | `FOREGROUND_SERVICE` | Normal | Run the MCP server as a foreground service |
  444. | `FOREGROUND_SERVICE_SPECIAL_USE` | Normal | Foreground service type for the MCP server |
  445. | `FOREGROUND_SERVICE_LOCATION` | Normal | Foreground service type for the Event Channel (geofence/WiFi) |
  446. | `FOREGROUND_SERVICE_DATA_SYNC` | Normal | Foreground service type for the free E2E tunnel enrollment (name + certificate) |
  447. | `RECEIVE_BOOT_COMPLETED` | Normal | Auto-start the server on device boot |
  448. | `QUERY_ALL_PACKAGES` | Normal | Enumerate installed apps for app-management tools |
  449. | `KILL_BACKGROUND_PROCESSES` | Normal | Stop background apps via app-management tools |
  450. | `ACCESS_WIFI_STATE` | Normal | Read WiFi state for the Event Channel |
  451. | `CHANGE_WIFI_STATE` | Normal | Manage WiFi for the Event Channel |
  452. | `POST_NOTIFICATIONS` | Runtime | Show the foreground service notification (Android 13+) |
  453. | `CAMERA` | Runtime | Camera photo/video MCP tools |
  454. | `RECORD_AUDIO` | Runtime | Audio capture for camera video tools |
  455. | `ACCESS_FINE_LOCATION` | Runtime | Location tools and geofence events |
  456. | `ACCESS_COARSE_LOCATION` | Runtime | Approximate location |
  457. | `ACCESS_BACKGROUND_LOCATION` | Runtime | Location/geofence events while the app is in the background |
  458. | `NEARBY_WIFI_DEVICES` | Runtime | WiFi scanning for the Event Channel (Android 13+) |
  459. | `READ_MEDIA_IMAGES` | Runtime | "All files" mode for built-in image storage locations (Android 13+) |
  460. | `READ_MEDIA_VIDEO` | Runtime | "All files" mode for built-in video storage locations (Android 13+) |
  461. | `READ_MEDIA_AUDIO` | Runtime | "All files" mode for built-in audio storage locations (Android 13+) |
  462. | `moe.shizuku.manager.permission.API_V23` | Runtime (Shizuku) | Optional elevated shell commands through Shizuku; granted in the Shizuku app or with Settings → Shell → Grant access (declared by the Shizuku client library) |
  463. | Accessibility Service | Special access | UI introspection, action execution, and screenshots — **required** for core functionality |
  464. | Notification Listener | Special access | Reading and managing notifications via notification tools |
  465. ---
  466. ## Security
  467. ### No Root Required
  468. The application runs entirely within Android's standard permission model. No root access, no unlocked bootloader, no custom ROM required.
  469. ### Optional Elevated Shell Commands
  470. The shell tools can run single commands with more power than the app has, only after you turn on **Settings → Shell → Allow elevated commands** (off by default). An elevated command runs through [Shizuku](https://shizuku.rikka.app/) as the adb shell user (or as root when Shizuku runs as root) or, when Shizuku is not usable, through `su` as root. Each elevated command carries a justification from the client and passes your rules: the blocklist always refuses, auto-allow or the allowlist let it run, and otherwise the phone asks you to approve it (Approve and Deny need the phone unlocked). Every elevated command is written to the server log (an entry keeps at most its first 500 bytes, so the end of a very long command can be missing). If you turn this on while the app is running, tap **Restart app** in the Shizuku row so Shizuku can connect (the app closes and opens again by itself; a running server starts again). The app itself never needs root; Shizuku or root are used only for these commands.
  471. Normal (not elevated) shell commands run as the app itself: they can read and change the app's own files, including its settings, and they can use any `su` grant or Shizuku access you gave the app. An MCP client that can use the notification, accessibility or intent tools can approve its own elevation request, so the approval is a check for you, not a boundary against such a client. If the app process dies while elevated commands run through `su`, some root managers (for example Magisk) keep those commands running until they end on their own. The shell tools are on by default: turn them off in Settings → MCP Tools unless you trust your MCP clients, turn on elevation only for clients you trust, and keep authentication on.
  472. ### Trust Model
  473. The accessibility service is the trust boundary. Once you grant it, an authenticated client controls the device as you do: it reads the screen and taps any control, including the app's own settings and the OAuth approval screen. The in-app toggles (per-location read/write/delete, per-tool enable/disable, and OAuth approval) express intent and prevent mistakes. They are not a sandbox around a client that already holds accessibility, which can change them the same way you would, through the UI or an intent.
  474. ### Authentication
  475. Authentication is combined (dual-accept): a `/mcp` request is authorized by a valid static bearer token OR a valid issued OAuth access token. Enforcement is controlled by two independent toggles in **Settings → Access** — `bearer_token_enabled` (default on) and `oauth_enabled` (default on) — not by the token value. The bearer token is auto-generated once on first launch (UUID, preserved across app upgrades) and can be viewed, copied, or regenerated in the app. Clearing the value while bearer is enabled makes the server fail CLOSED (401). The server accepts unauthenticated requests only when BOTH toggles are off (the app shows a warning and a confirmation before that happens) — see the security note in the Connect section.
  476. ### Network Security
  477. - **Default binding `127.0.0.1`**: Only accessible via adb port forwarding or tunnels (most secure)
  478. - **Optional binding `0.0.0.0`**: Accessible over network (use only on trusted networks; security warning displayed when enabling)
  479. - **Optional specific IP**: Listens on that address only (plus `127.0.0.1` for an enabled tunnel), so normally only the network of that address reaches it (same security warning)
  480. - **HTTPS**: Optional, disabled by default. When enabled, uses auto-generated self-signed certificates or upload your own CA-signed certificate. Certificate is stored in app-private storage.
  481. ### Permissions
  482. All permissions are managed from the app's Settings > Permissions tab. Every sensitive permission requires explicit user action — nothing is granted silently. The optional Shizuku access for elevated shell commands is granted in Settings → Shell or in the Shizuku app, and `su` grants come from your root manager.
  483. Storage locations are configured in Settings > Storage, which includes automatic locations (e.g., Downloads) and custom locations authorized via the system file picker.
  484. ---
  485. ## Contributing
  486. See [CONTRIBUTING.md](CONTRIBUTING.md) for build requirements, testing, architecture, and development conventions.
  487. ---
  488. ## License
  489. This project is licensed under the GNU General Public License, version 3 or (at your option) any later version,
  490. with an additional permission under GPLv3 section 7 for combining it with the Google Play services client libraries.
  491. See [LICENSE.md](LICENSE.md) for the full text.
  492. Third-party components bundled with the app and their licenses are listed in
  493. [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.