android-remote-control-mcp

远程控制 MCP [简体中文说明](README.zh-CN.md) [](https://github.com/mei-shui-xing/android-remote-control-mcp/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) 一款运行在 Android 设备上的应用程序，作为 **MCP（模型上下文协议）服务器**，使 AI 模型能够使用无障碍服务和截图功能远程完全控制 Android 设备。 该应用程序直接在您的 Android 设备（或模拟器）上运行，并公开一个 HTTP 服务器（可选 HTTPS），实现 MCP 协议。像 Claude 这样的 AI 模型可以连接到它并与设备上的任何应用程序交互 — 读取 UI 元素、点击按钮、输入文本、滑动、捕获截图、管理文件、启动应用程序等。 > **警告：** 本软件仅供 **研究和教育目的**，不提供任何形式的担保。作者不赞同将此工具用于任何非法、未经授权或不道德的活动。用户有责任确保其使用符合所有适用的法律法规。使用此软件即表示您责任地使用并承担风险。 > **Alpha 运行** 在启用远程访问之前，请在本地通过 USB 验证。Clash Meta 全球模式已通过一款 OriginOS 手机的，但不保证在 VPN、供应商或 Android 版本上兼容。在 AI 任务运行时，请将手机专交给 AI 使用，并从计算机继续聊天。设备所有者必须亲自处理锁屏凭证、生物识别、支付、OTP 代码、权限授予和任何其他敏感授权。在取回手机之前，请暂停远程触控。 --- ## 演示 <p align="center"> <img src="docs/assets/demo.gif" alt="AI 模型通过 MCP 服务器控制 Android 设备的演示" width="720"> </p> <p align="center"><em>AI 模型通过 MCP 服务器控制 Android 设备（加速）。</em></ 功能 ### MCP 服务器 - 直接在 Android 上运行的 HTTP 服务器（Ktor + Netty），可选 HTTPS - 在 `/mcp` 处的流式 HTTP 传输（符合 MCP 规范，仅 JSON，无 SSE） - 组合身份验证：静态 bearer token 和/或自包含的 OAuth 2.1 服务器（Claude.ai / Claude连接器，设备上批准） - 自动生成的自签名 TLS 证书（或自定义证书上传） - 可配置的绑定：本地主机（127.0.0.1）或网络（0.0.0.0） - 开 - 通过 Cloudflare Quick Tunnels 或 ngrok 的远程访问隧道（公共 HTTPS URL） ### 16 类别下的 66 种 MCP 工具 屏幕检测、系统操作、触摸操作、手势、节点操作、文本实用工具、文件操作、应用程序管理、使用和屏幕时间、相机、意图、通知、位置和共享。 所有工具名称默认使用 `android_`（例如 `android`）。配置设备（例如 `pixel），前缀变为 `android_`（例如 `android_pixel7_tap`） [docs/MCP.md](docs/MCP_TOOLS.md) 获取完整的工具参考，包含输入/输出模式和示例。 ### Android 应用程序 - 带有标签式布局（服务器/设置/关于）和暗模式的 Material Design 3 UI - 服务器状态监控（运行/停止）并带有权限警告横幅 - 连接信息IP、端口、令牌、隧道 URL） - 每个工具和每个参数的权限（启用/禁用单个 MCP 工具） - 权限无障碍、用法访问、通知、相机、麦克风） - 持久化通知开关，暂停或恢复远程触摸和文本输入 - 远程访问隧道配置（Cloudflare / ngrok） - 存储位置管理（自动位置 + 文件工具的 SAF 授权） - 服务器日志查看器（MCP 工具调用、隧道事件） - 通过 ADB 进行无头设置（配置、授予权限、启动/停止服务器，无需 UI） ### 与替代品的比较 | 功能 | 本项目 | [mobile-mcp] | [Android-MCP] | [android-mcp-server] | [adb-mcp] | [droidrun-mcp] | |---------|:-:|:-:|:-:|:-:|:-:|:-:| | MCP 工具 | 66 | 21 | 11 | 5 | 10 | 11 | | 在手机上运行（无需 ADB） | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | | 操作延迟 | 10-100 毫秒 | 1-4 秒 | 1-4 秒 | 1-4 秒 | 1-4 秒 | 1-4 秒 | | 支持互联网 | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | | 令牌高效的屏幕状态 | :white_check_mark: | :x: | :white_check_mark: | :x: | :x: | :white_check_mark: | | 带有注释的截图 | :white_check_mark: | :x: | :white_check_mark: | :x: | :x: | :x: | | 可配置的截图分辨率/质量 | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | | 每个工具启用/禁用 | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | | 多设备支持 | :white_check_mark: | :white_check_mark: | :x: | :x: | :xx: | | 相机、文件、下载 | :white_check_mark:x: | :x: | :x: | :x: | :x: | | iOS 支持 | :x: |_check_mark: | :x: | :x: | :x: | :x: | [mobile-m https://github.com/mobile-next/mobile-mcp CP]: https://github.com/CursorTouch/Android [android-mcp-server]: https://githubvp/android-m[adb-mcp]: https://github.com/s/adb-m[droidrun-mcp]: https://github.com/chukfinley/droidrun-mcp-server 大多数替代于主机计算机上的 ADB，这意味着需要一根 USB 数据线或本地网络连接台计算机放在手机旁边。该项目完全在设备本身运行，因此您可以将 MCP 端点通过隧道暴露出来，并从任何地方控制您的手机。 在令牌效率方面，基于 ADB 的工具通常会返回原始的 `uiautomator` XML 转储，这可能比这里使用的紧凑表示法多 10-50 倍。结合编号的截图注释、可配置的图像质量以及禁用不需要的工具（每个工具定义都会中消耗令牌），这显著降低了代理循环中的每次交互成本。 --- ## 安装 ### 选项 A：在手机上下载（最简单） 1手机浏览器上打开 [Releases](https://github.com/mei-shui-xing/android-remote-control-mcp/releases) 页面 2. 下载最新版本发布的 APK 3. 打开下载的 APK 并按照提示安装（您可能需要允许来自未知来源的安装） ### 选项 B：在 PC 上下载并通过 ADB 安装 1. 从 [Releases](https://github.com/mei-shui-xing/android-remote-control-mcp/releases) APK 2. 通过 USB 连接手机（启用 USB 调试） 3. 安装 APK： ```bash adb install app-release.apk ``` ### 选项 C：从源代码构建 ```bash git clone https://github.com/mei-shui-xing/android-remote-control-mcp.git cd android-remote-control-mcp make build make install # 安装到连接的设备/模拟器 ``` 参见 [CONTRIBUTINGCONTRIBUTING 获取完整的构建要求和说明。 ### 使用 USB 和 AI 辅助设置 对于首次安装，将手机通过 USB 连接到计算机，启用试，并使用带有存储库 PowerShell 脚本信任 AI 编码助手。助手可以帮助验证 ADB 授权、构建和安装 APK、检查非敏感权限状态、创建临时端口转发、收集删减日志以及运行无害的烟雾测试。 该项目是 Alpha 版本，不为 OEM Android 变体、VPN/代理配置程序、Android SDK 安装或个人计算机环境提供设备支持。如有错误、删减日志和文档，请提供给 AI 助手进行自我服务诊断。这不授权 AI 绕过 Android 安全边界：设备所有者必须亲自处理锁屏凭证、生物识别、帐户登录、OTP、支付、权限对话框和所有其他敏感确认。永远不要在问题中发布 bearer 令牌、凭证或私人对话。 --- ## 设置 1. **打开应用程序**，进入设置 > 权限 2. **启用无障碍服务**（用于 UI 检测、操作和截图） 3. **授予其他权限**（如果需要）（相机、麦克风、位置、通知） 4. **配置存储位置**（在设置 > 存储中），如果您计划使用文件工具（包括自动位置，如下载，以及通过 SAF 的自定义位置） 5. 返回到 **服务器选项卡**，点击 **启动** 以启动 MCP 服务器 服务器默认在 `http://127.0.0.1:8080` 启动。连接信息（IP、端口、令牌、URL）在服务器选项卡上显示。 > **注意**：`127.0.0.1` 指的是手机的本地主机，而不是您的计算机。要从计算机连接，请使用 [adb 端口转发](#using-with-adb-port-forwarding)、绑定到 `0.0.0.0`（网络模式）或启用 [远程访问隧道](#using-remote-access-tunnels)。 ### 权限参考 应用程序声明以下权限。**普通** 权限在安装时自动授予。**运行时** 权限和**特殊访问** 需要用户明确操作（通过应用程序的设置 > 权限选项卡，或通过编程方式 - 参见 [编程方式授予权限](docs/PERMISSIONS.md)）。所有运行时权限都是可选的：应用程序在没有它们的情况下工作，但依赖它们的特性在授予之前被禁用。 | 权限 | 类型 | 用途 | |------------|------|----------| | `INTERNET` | 普通 | HTTP/HTTPS 服务器和远程访问隧道 | | `ACCESS_NETWORK_STATE` | 普通 | 检测网络连接性 | | `FOREGROUND_SERVICE` | 普通 | 将 MCP 服务器作为前台服务运行 | | `FOREGROUND_SERVICE_SPECIAL_USE` | 普通 | MCP 服务器的前台服务类型 | | `FOREGROUND_SERVICE_LOCATION` | 普通 | 事件通道（地理围栏/WiFi）的前台服务类型 | | `RECEIVE_BOOT_COMPLETED` | 普通 | 设备启动时自动启动服务器 | | `QUERY_ALL_PACKAGES` | 普通 | 枚举已安装的应用程序，用于应用程序管理工具 | | `KILL_BACKGROUND_PROCESSES` | 普通 | 通过应用程序管理工具停止后台应用程序 | | `ACCESS_WIFI_STATE` | 普通 | 读取 WiFi 状态，用于事件通道 | | `CHANGE_WIFI_STATE` | 普通 | 管理事件通道的 WiFi | | `POST_NOTIFICATIONS` | 运行时 | 显示前台服务通知（Android 13+） | | `CAMERA` | 运行时 | 相机照片/视频 MCP 工具 | | `RECORD_AUDIO` | 运行时 | 相机视频工具的音频捕获 | | `ACCESS_FINE_LOCATION` | 运行时 | 位置工具和地理围栏事件 | | `ACCESS_COARSE_LOCATION` | 运行时 | 近似位置 | | `ACCESS_BACKGROUND_LOCATION` | 运行时 | 应用程序在后台时的位置/地理围栏事件 | | `NEARBY_WIFI_DEVICES` | 运行时 | 事件通道的 WiFi 扫描（Android 13+） | | `READ_MEDIA_IMAGES` | 运行时 | 构建存储位置的“所有文件”模式（Android 13+） | | `READ_MEDIA_VIDEO` | 运行时 | 构建存储位置的“所有文件”模式（Android 13+） | | `READ_MEDIA_AUDIO` | 运行时 | 构建存储位置的“所有文件”模式（Android 13+） | | 无障碍服务 | 特殊访问 | UI 检测、操作执行和截图 - **核心功能所需** | | 通知监听器 | 特殊访问 | 通过通知工具读取和管理通知 | | `PACKAGE_USAGE_STATS` / 用法访问 | 特殊访问 | 应用程序前台时间和屏幕时间工具 | --- ## 连接 ### Claude Desktop / Claude 代码 将服务器添加到您的 `.mcp.json` 配置文件中： ```json { "mcpServers": { "android-phone": { "type": "http", "url": "http://DEVICE_IP:PORT/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` 用应用程序服务器选项卡中显示的值替换 `DEVICE_IP`、`PORT` 和 `YOUR_TOKEN`。如果服务器绑定到本地主机（默认），您需要 [adb 端口转发](#using-with-adb-port-forwarding) 或 [远程访问隧道](#using-remote-access-tunnels) 来连接。 > **适用于不支持自定义标头客户端的说明：** 如果您的 MCP 客户端无法发送 `Authorization` 标头并且不支持 OAuth，您可以在应用程序中关闭这两种身份验证方法（**设置 → 访问** - 禁用 Bearer 令牌和 OAuth）。应用程序会发出警告并要求您确认，因为服务器现在是 **开放的**：任何可以访问它的人都具有完全控制权。只有在您信任的网络中才这样做。 ### 从 Claude.ai 和 Claude Desktop 连接（自定义连接器，OAuth） Claude.ai（网页版）和 Claude Desktop 作为 **自定义连接器**（远程 MCP）使用 OAuth 2.1 - 应用程序是其自己的 OAuth 授权服务器，因此不需要外部帐户或预注册。这需要服务器通过 **公共 HTTPS URL** 可访问，因此您必须首先启用 [远程访问隧道](#using-remote-access-tunnels) - `localhost` / LAN 地址或 `adb` 端口转发将 **不** 起作用。 1. **OAuth 默认启用** - 无需操作（如果您之前禁用了它，请在 **设置 → 访问** 下重新启用）。Bearer 令牌也保持启用；两者都接受。 2. 打开 **设置 → 隧道**，启用 **远程访问**（Cloudflare Quick Tunnels 不需要帐户），并启动服务器。复制服务器选项卡中的公共 `https://…` URL，并追加 `/mcp`（例如 `https://your-tunnel.trycloudflare.com/mcp`）。 3. 在 Claude 中，打开 **[自定义 → 连接器 → 添加自定义连接器](https://claude.ai/customize/connectors?modal=add-custom-connector)**，粘贴 `https://…/mcp` URL，**并将 OAuth 客户端 ID 和客户端密钥留空**（应用程序使用动态客户端注册 **添加**。 4. Claude 打开一个浏览器批准页面，显示一个 **2 位数字代码**。在设备上，会出现一个浮动通知 - 点击它打开应用程序内的批准屏幕，确认代码匹配并 **批准**。 5. 在 **设置 → 访问 → 已连接的客户端撤销已连接的客户端。撤销会立即使该客户端的失效。 > **公共 URL 覆盖（可选）：** 如果您的隧道/主机拓扑需要固定公共主机（或您绑定0.0.0.0` 且没有受信任的代理），请在设置 → 访问中设置 **公共 URL 覆盖**，以便 OAuth 元数据和链接使用稳定主机。 自定义连接器在免费（1 个连接器）、Pro、Max、Team 和 Enterprise 计划（目前处于测试阶段）上可用。 > ⚠️ **安全：** 请将公共隧道 URL 视为敏感信息，只批准您发起的连接（验证 2 位数字代码），撤销不再使用的客户端，并在完成后停止隧道和服务器。永远不要将其指向包含敏感数据的设备。 ### 其他 MCP 客户端 MCP 服务器在 `/mcp` 处暴露一个标准的 Streamable HTTP 端点，带有组合身份验证（静态 bearer 令牌和/或 OAuth 2.1）。任何 MCP 兼容的客户端都可以连接到它 - 请参阅您客户端的文档以获取特定的配置格式。 ### 使用 MCP 检测器进行测试 [MCP 检测器](https://github.com/modelcontextprotocol/inspector) 是 MCP 服务器的官方视觉测试工具。它提供了一个基于浏览器的 UI，用于连接、列出工具、填充参数和查看响应： ```bash npx @modelcontextprotocol/inspector ``` 这会在 `http://localhost:6274` 打开一个 UI，您可以在那里连接您的服务器并交互式地测试工具。 ### 使用 curl 测试 所有请求都作为 JSON-RPC 2.0 发送到 `POST /mcp`（Streamable HTTP 传输）。服务器在工具调用之前需要一个会话初始化握手： ```bash # 初始化会话（在任何工具调用之前需要） # 从响应头中捕获 mcp-session-id curl -s -D- -X POST http://localhost:8080/mcp \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}' # 使用响应头中的 mcp-session-id 进行后续请求 # 列出可用工具 curl -X POST http://localhost:8080/mcp \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "mcp-session-id: SESSION_ID" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' # 获取当前屏幕状态（UI 节点 + 可选截图） curl -X POST http://localhost:8080/mcp \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "mcp-session-id: SESSION_ID" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"android_get_screen_state","arguments":{}}}' # 点击坐标 curl -X POST http://localhost:8080/mcp \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "mcp-session-id: SESSION_ID" \ -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"android_tap","arguments":{"x":540,"y":1200}}}' ``` 用响应头中的 `mcp-session-id` 值替换 `SESSION_ID`。 Bearer 令牌在应用程序的连接信息中显示，可以直接复制。Bearer 身份验证由 **设置 → 访问** 中的 **Bearer 令牌** 开关控制（不是清除值）：启用后，每个 `/mcp` 请求都必须包含令牌（或有效的 OAuth 访问令牌）。服务器仅在 **两者** Bearer 令牌和 OAuth 都禁用时接受未经身份验证的请求。 --- ## 配置 // ... (rest of the document remains the same) ### 服务器设置（通过应用界面） | 设置 | 默认值 | 描述 | |---------|---------|-------------| | 端口 | `8080` | HTTP/HTTPS 服务器端口 | | 绑定地址 | `127.0.0.1` | `127.0.0.1`（本地主机，用于 adb 端口转发）或 `0.0.0.0`（网络，所有接口） | | Bearer Token | 已启用，自动生成的 UUID | MCP 请求的静态令牌（设置 → 访问） | | OAuth | 已启用 | 用于 Claude.ai / Claude Desktop 自定义连接器的自包含 OAuth 2.1 服务器（设置 → 访问） | | 公共 URL 覆盖 | 空（自动检测） | 固定用于 OAuth 元数据和共享链接的公共主机 | | HTTPS | 已禁用 | 启用 HTTPS，带有自动生成的自签名证书（可配置主机名）或上传自定义 .p12/.pfx | | 自动启动（开机） | 已禁用 | 设备启动时自动启动 MCP 服务器 | | 设备标识符 | 空 | 工具名称前缀的可选设备标识符（例如，`pixel7` 使得工具为 `android_pixel7_tap`） | | 远程访问隧道 | 已禁用 | 通过公共 HTTPS URL 暴露服务器（Cloudflare Quick Tunnels 或 ngrok） | | 工具权限 | 全部启用 | 每工具和每参数启用/禁用（设置 > MCP 工具） | | 文件大小限制 | 50 MB | 文件操作的最大文件大小（范围 1-500 MB） | | 允许 HTTP 下载 | 已禁用 | 通过 `android_download_from_url` 允许非 HTTPS 下载 | | 下载超时 | 60 秒 | 文件下载的超时时间（范围 10-300 秒） | ### 使用 adb 端口转发 当服务器绑定到 `127.0.0.1`（默认，最安全）： ```bash # 将设备端口转发到主机 adb forward tcp:8080 tcp:8080 # 从主机测试连接 curl -X POST http://localhost:8080/mcp \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' ``` ### 在网络上使用 当服务器绑定到 `0.0.0.0`： 1. 查找设备的 IP 地址（在应用的连接信息中显示） 2. 通过 `POST http://DEVICE_IP:8080/mcp` 直接连接，带有 bearer token **警告**：绑定到 `0.0.0.0` 会将服务器暴露给同一网络上的所有设备。仅在受信任的私有网络上使用。 ### 使用远程访问隧道 用于从本地网络外部连接，无需端口转发： 1. **Cloudflare Quick Tunnels**（默认，无需帐户）：创建具有随机 `*.trycloudflare.com` HTTPS URL 的临时隧道。 2. **ngrok**（需要帐户）：支持可选的自定义域。需要 ngrok authtoken（提供免费层）。可在 arm64-v8a 和 x86_64 设备上使用。 在应用的“远程访问”部分启用隧道。公共 URL 在连接信息和服务器日志中显示。 ### 通过 ADB 进行无头设置 应用可以完全从命令行配置和控制，无需打开 UI。这对于自动化设置、CI 管道或无头设备非常有用。 将 `<app-id>` 替换为您的构建的应用 ID： - **调试**：`com.danielealbano.androidremotecontrolmcp.debug` - **发布**：`com.danielealbano.androidremotecontrolmcp` #### 授予权限 ```bash # 启用无障碍服务（需要 UI 反省、操作和截图） adb shell settings put secure enabled_accessibility_services \ <app-id>/com.danielealbano.androidremotecontrolmcp.services.accessibility.McpAccessibilityService # 启用通知监听服务（需要通知工具） adb shell cmd notification allow_listener \ <app-id>/com.danielealbano.androidremotecontrolmcp.services.notifications.McpNotificationListenerService # 授予通知权限（Android 13+） adb shell pm grant <app-id> android.permission.POST_NOTIFICATIONS # 授予相机权限 adb shell pm grant <app-id> android.permission.CAMERA # 授予麦克风权限 adb shell pm grant <app-id> android.permission.RECORD_AUDIO # 授予位置权限 adb shell pm grant <app-id> android.permission.ACCESS_FINE_LOCATION adb shell pm grant <app-id> android.permission.ACCESS_COARSE_LOCATION adb shell pm grant <app-id> android.permission.ACCESS_BACKGROUND_LOCATION # 授予附近 WiFi 设备权限（Android 13+） adb shell pm grant <app-id> android.permission.NEARBY_WIFI_DEVICES # 授予媒体读取权限（Android 13+） adb shell pm grant <app-id> android.permission.READ_MEDIA_IMAGES adb shell pm grant <app-id> android.permission.READ_MEDIA_VIDEO adb shell pm grant <app-id> android.permission.READ_MEDIA_AUDIO ``` 参阅 [docs/PERMISSIONS.md](docs/PERMISSIONS.md) 以获取完整参考和一次性授予所有权限的复制粘贴脚本。 #### 配置应用 所有额外参数都是可选的 — 仅更新提供的参数。应用**不需要**打开。 ```bash adb shell am broadcast \ -a com.danielealbano.androidremotecontrolmcp.ADB_CONFIGURE \ -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbConfigReceiver \ --es bearer_token "my-secret-token" \ --es binding_address "0.0.0.0" \ --ei port 8080 \ --ez auto_start_on_boot true \ --ez https_enabled false \ --es certificate_source "AUTO_GENERATED" \ --es certificate_hostname "mcp.local" \ --ez tunnel_enabled false \ --es tunnel_provider "CLOUDFLARE" \ --es ngrok_authtoken "your-ngrok-token" \ --es ngrok_domain "your-domain.ngrok-free.app" \ --ei file_size_limit_mb 50 \ --ez allow_http_downloads false \ --ez allow_unverified_https_certs false \ --ei download_timeout_seconds 60 \ --es device_slug "pixel8" \ --es tool_permissions '{"disabled_tools":["tap"],"disabled_params":{"swipe":["duration_ms"]}}' ``` ```bash # 禁用 bearer 身份验证（仅在受信任的网络中使用；如果 OAuth 也禁用，则服务器打开） adb shell am broadcast \ -a com.danielealbano.androidremotecontrolmcp.ADB_CONFIGURE \ -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbConfigReceiver \ --ez bearer_token_enabled false ``` Bearer 执行由 `--ez bearer_token_enabled <bool>` 控制，而不是通过清除值。清除值（`--es bearer_token ""`）同时 `bearer_token_enabled=true` 使 `/mcp` 失败 CLOSED（401）- 它**不**打开服务器。只有当 `bearer_token_enabled` 和 `oauth_enabled` 均为 false 时，服务器才接受未经身份验证的请求。 | 额外参数 | 类型 | 描述 | |-------|------|-------------| | `bearer_token` | 字符串 | 静态 bearer-token 值（清除时 `bearer_token_enabled=true` 失败关闭，不禁用身份验证） | | `bearer_token_enabled` | 布尔值 | 启用/禁用 bearer-token 身份验证（控制执行，独立于值） | | `oauth_enabled` | 布尔值 | 启用/禁用自包含的 OAuth 2.1 服务器（Claude.ai / Claude Desktop 连接器） | | `public_url_override` | 字符串 | 固定用于 OAuth 元数据和共享链接的公共主机（空 = 从请求自动检测） | | `binding_address` | 字符串 | `127.0.0.1`（本地主机）或 `0.0.0.0`（网络） | | `port` | 整数 | HTTP/HTTPS 服务器端口（1-65535） | | `auto_start_on_boot` | 布尔值 | 设备启动时启动 MCP 服务器 | | `https_enabled` | 布尔值 | 启用 HTTPS，带有 TLS | | `certificate_source` | 字符串 | `AUTO_GENERATED` 或 `CUSTOM` | | `certificate_hostname` | 字符串 | 自动生成的证书的主机名 | | `tunnel_enabled` | 布尔值 | 启用远程访问隧道 | | `tunnel_provider` | 字符串 | `CLOUDFLARE` 或 `NGROK` | | `ngrok_authtoken` | 字符串 | ngrok 身份验证令牌 | | `ngrok_domain` | 字符串 | ngrok 自定义域（可选） | | `file_size_limit_mb` | 整数 | 文件操作的最大文件大小（1-500） | | `allow_http_downloads` | 布尔值 | 允许非 HTTPS 下载 | | `allow_unverified_https_certs` | 布尔值 | 允许未经验证的 HTTPS 证书用于下载 | | `download_timeout_seconds` | 整数 | 下载超时（10-300） | | `device_slug` | 字符串 | 工具名称前缀的设备标识符 | | `tool_permissions` | 字符串（JSON） | 每工具和每参数权限：`{"disabled_tools":["tool_name"],"disabled_params":{"tool_name":["param"]}}` | #### 启动 MCP 服务器 服务器必须通过 trampoline Activity 启动（在 Android 12+ 上需要，以获得前台服务豁免）。即使应用被强制停止，此操作也有效。 ```bash adb shell am start \ -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbServiceTrampolineActivity \ --es action start ``` #### 停止 MCP 服务器 ```bash adb shell am start \ -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbServiceTrampolineActivity \ --es action stop ``` --- ## 安全 ### 无需 Root 应用程序完全在 Android 的标准权限模型中运行。无需 root 访问，无需解锁引导加载程序，无需自定义 ROM。 ### 身份验证 身份验证是组合的（双重接受）：`/mcp` 请求由有效的静态 bearer token 或有效的颁发的 OAuth 访问令牌授权。执行由 **设置 → 访问** 中的两个独立开关控制 — `bearer_token_enabled`（默认开启）和 `oauth_enabled`（默认开启） — 而不是令牌值。bearer token 在首次启动时自动生成一次（UUID，保留跨应用升级），可以在应用中查看、复制或重新生成。清除值同时 bearer 已启用会使服务器失败 CLOSED（401）。只有当两个开关都关闭时（应用在发生这种情况之前显示警告和确认），服务器才接受未经身份验证的请求 — 参见连接部分的安全说明。 ### 网络安全 - **默认绑定 `127.0.0.1`**：仅可通过 adb 端口转发或隧道访问（最安全） - **可选绑定 `0.0.0.0`**：可在网络上访问（仅在受信任的网络中使用；启用时显示安全警告） - **HTTPS**：可选，默认禁用。启用时，使用自动生成的自签名证书或上传您自己的 CA 签名证书。证书存储在应用私有存储中。 ### 权限 所有权限都从应用的设置 > 权限选项卡进行管理。每个敏感权限都需要明确的用户操作 — 不会默默授予任何权限。 存储位置在设置 > 存储中配置，包括自动位置（例如，下载）和通过系统文件选择器授权的自定义位置。 --- ## 贡献 参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取构建要求、测试、架构和开发约定。 --- ## 许可证 该项目根据 MIT 许可证授权。有关详细信息，请参阅 [LICENSE.md](LICENSE.md)。 ## 相关项目 有关 Douyin、Windows PC 和 Android 手机 MCP 项目的统一入口点，请参阅 [mcp-tools-link-hub](https://github.com/mei-shui-xing/mcp-tools-link-hub)。