mobile-debug-mcp

mobile-debug [](https://github.com/Techmanu-PVT-LTD/mobile-debug-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/downloads/) 一个 MCP 服务器，允许 Claude 像 QA 工程师一样驱动真正的 Android 应用在模拟器或设备上：**启动、观察、操作、验证**，并以日志和截图作为证据。 与薄的“adb over MCP”包装不同，每个操作都会返回**新的屏幕状态**和**日志增量**，因此输出不是“我点击了一个按钮”，而是“我点击了**登录**，应用程序发送了 `/auth`，得到了一个 `401`，并显示了一个错误提示信息 —— 以下是截图和日志行。” 它还会**随着使用学习应用程序**。它看到的每个屏幕都成为导航图中的一个节点，每个操作都成为一条边，因此当您第二次需要设置时，代理会走一条已知的路线，而不是重新探索 UI —— 这是代理 QA 中令牌成本实际发生的地方。 > 状态：**早期** —— 原始工具表面加上应用程序地图和第一个语义操作。Flutter 画布屏幕通过语义树处理。参见 [PLAN.md](PLAN.md)。 ## 演示  Claude 被要求注销并登录“并检查是否有任何错误”。它读取屏幕，通过点击操作，并报告应用程序**实际**执行的操作 —— 无需手写的选择器。高质量的录制：[`media/demo.mp4`](media/demo.mp4)。 ## 快速入门 在运行模拟器并将 `adb` 添加到 `PATH` 中： ```bash uv sync --extra dev --extra images uv run mobile-debug-mcp --transport http # http://127.0.0.1:8765/mcp ``` 使用 Claude Code 注册它，然后让代理学习它的使用方法： ```bash claude mcp add --transport http mobile-debug http://127.0.0.1:8765/mcp ``` ```bash launch_app("com.example.app") → 初始屏幕，元素索引，加上启动日志 map_app() → 爬取应用程序，有界，构建导航地图 get_map() →每个屏幕及其到达方式 navigate_to("设置") → 重放已知路线：首页 —[点击 '菜单']→ 抽屉 → 设置 ``` `navigate_to("设置", plan_only=True)` 打印路线而无需触摸设备。 ## 要求 - Python 3.11+ - Android `platform-tools` 在 `PATH` 上（`adb`） - 运行中的模拟器或通过 USB 连接的设备 设备选择：设置 `ANDROID_SERIAL`，或传递 `--device <serial>`。如果连接一个设备，则自动选择；如果有零个或多个设备且没有选择，则服务器清楚地报错。 ## 运行 两种传输方式。请选择一种。 ### HTTP — 长寿命本地守护进程（推荐） ```bash uv run mobile-debug-mcp --transport http # http://127.0.0.1:8765/mcp ``` 一个守护进程为机器上的每个项目提供服务，因此客户端配置不携带绝对路径 — 将其提交到任何需要这些工具的仓库： ```json { "mcpServers": { "mobile-debug": { "type": "http", "url": "http://127.0.0.1:8765/mcp" } } } ``` 会话的生命周期长于任何单个客户端，因此学习到的应用程序地图和 logcat 游标在 Claude 会话之间持续存在，而不是每次都重新构建。代价是**您**启动它 — 没有自动生成，它会在关闭时客户端连接失败。 由于表面现在可通过网络访问，因此 HTTP 模式会加强 stdio 默认情况下的两个功能： - **截图写入被沙盒化**到 `~/.config/mobile-debug-mcp/artifacts`（使用 `--artifacts-dir` 移动）。否则，`take_screenshot(save_path=…)` 是一个任意文件写入基元。 - **DNS 重新绑定保护已启用**，因此浏览器中的网页无法向该端口发送 POST 请求。MCP SDK 默认情况下将其**关闭**；此服务器将其打开。 操作在设备锁下序列化 — 一个设备，一个屏幕，因此两个并发客户端无法交织操作。这可以防止操作损坏，但不能防止逻辑竞争：两个客户端驱动同一个设备仍然会相互混淆，因此不要这样做。 `--host` 绑定到其他位置，但**没有身份验证** — 任何可以访问该端口的人都可以驱动设备，读取 logcat（令牌，PII）并清除应用数据。如果您绑定到环回地址以外的地址，它会发出警告。不要在没有在它前面添加身份验证的情况下绑定。 ### stdio — 每个客户端一个进程 ```bash uv run mobile-debug-mcp ``` ```bash claude mcp add mobile-debug -- uv run --directory /abs/path/to/mobile-debug-mcp mobile-debug-mcp ``` 由客户端自动生成，无需保持运行 — 但绝对路径意味着注册不会在不同机器之间传递，并且每次会话都会重新构建状态。`save_path` 在此处不受限制，因为客户端已经拥有该进程。 ## 工具 **基元** — 每个基元都返回新的屏幕状态和它产生的日志增量。 | 工具 | 功能 | |---|---| | `launch_app` | 强制停止 → 可选 `pm clear` → 启动；返回屏幕状态 | | `get_screen_state` | 紧凑的元素列表（+ 可选的缩略截图） | | `tap_element` | 点击元素 ID（或 `x,y`）；返回新状态 + 日志增量 | | `input_text` | 聚焦字段并输入（目前仅 ASCII） | | `take_screenshot` | 纯图像，无层次结构转储 — 适用于画布/Flutter/视频屏幕 | | `get_logs` | PID 范围内的 logcat，已分类 | | `press_key` | 后退 / 首页 / 回车 / … | | `swipe` | 在两点之间滚动 / 拖动 | **应用程序地图** — 通过导航，而不是重新探索。 | 工具 | 功能 | |---|---| | `map_app` | 有界的自动爬取，填充地图；跳过破坏性控件 | | `get_map` | 每个已知屏幕及其到达方式 | | `navigate_to` | 声明路线，然后重放它，重新解析元素选择器 | **语义** — 确定性的感知→操作→验证状态机。 | 工具 | 功能 | |---|---| | `reset_app` | 重启或清除并重启，然后验证实际到达的位置 | | `go_home` | 路线 → 展开后退栈 → 重启，最便宜的第一；从不盲目按下 | ## 开发 ```bash uv run ruff check . uv run ruff format . uv run pytest # 无需设备 — adb 被模拟，屏幕来自固定装置 ``` 参见 [CONTRIBUTING.md](CON.md) 了解布局和约定，以及 [SE](SECURITY.md)地方公开 HTTP 传输之前。 ## 许可证 MIT © [Techmanu Pvt. Ltd.](https://github.com/Techmanu-PVT-LTD) — 参见 [LICENSE](LICENSE). 由 [@MaheshPhuyal02](https://github.com/MaheshPhuyal02) 维护。