Mobile Device Mcp

mobile-device-mcp

为 AI 编码助手（Claude Code、Cursor、Windsurf）提供查看和操作移动设备能力的 MCP 服务。提供 49 个工具，用于截屏、UI 检查、触控交互、AI 驱动的视觉分析、Flutter 小部件树检查、视频录制和测试生成。

AI 助手能读取你的代码，却看不到你的手机。这个工具解决了这个问题。

为什么选择它？

问题所在

Web 开发者有浏览器 DevTools、Playwright 和 Puppeteer，AI 助手可以点击、截屏并验证修复结果。移动开发者呢？他们只能手动截屏、复制日志，再描述屏幕上的内容。他们成了 AI 和设备之间的人工中间层。

功能介绍

Developer: "The login button doesn't work"

Without this tool:                    With this tool:
  1. Manually screenshot              1. AI calls take_screenshot -> sees the screen
  2. Paste into AI chat               2. AI calls smart_tap("login button") -> taps it
  3. AI guesses what's wrong          3. AI calls verify_screen("error message shown") -> sees result
  4. Apply fix, rebuild               4. AI calls visual_diff -> confirms fix worked
  5. Repeat 4-5 times                 5. Done.

快速开始

安装

npx mobile-device-mcp

无需全局安装，可通过 npx 直接运行。

前提条件

• Node.js 18+
• 通过 ADB 连接的 Android 设备/模拟器
• 已安装 ADB（Android SDK Platform Tools）

设置（一次性，30 秒）

1. 获取 Google AI 密钥（提供免费套餐）：aistudio.google.com/apikey

2. 在项目根目录添加 .mcp.json：

macOS / Linux：

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key"
      }
    }
  }
}

使用 Pro 许可证密钥（购买 Pro 后）：

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "MOBILE_MCP_LICENSE_KEY": "MDMCP-XXXXX-XXXXX-XXXXX-XXXXX"
      }
    }
  }
}

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "MOBILE_MCP_LICENSE_KEY": "MDMCP-XXXXX-XXXXX-XXXXX-XXXXX"
      }
    }
  }
}

3. 从该目录打开 AI 编码助手。 就这么简单。

服务会自动启动和停止，无需手动运行。AI 助手会通过 MCP 协议将其作为后台进程进行管理。

验证是否正常运行

Claude Code： 输入 /mcp，你应该会看到 mobile-device: Connected

Cursor： 在设置中的 MCP 面板查看

然后直接和手机说：

You: "Open my app, tap the login button, type [email protected] in the email field"
AI:  [takes screenshot -> sees the screen -> smart_tap("login button") -> smart_type("email field", "[email protected]")]

You: "Find all the bugs on this screen"
AI:  [analyze_screen -> inspects layout, checks for overflow, missing labels, broken states]

You: "Navigate to settings and verify dark mode works"
AI:  [smart_tap("settings") -> take_screenshot -> smart_tap("dark mode toggle") -> visual_diff -> reports result]

无需测试脚本，无需手动截屏。只需用普通语言描述你想做什么。

适用于任何 AI 编码助手

所有工具都使用相同的 JSON 配置——只需将其放入编辑器对应的文件中。

集成到任何项目

将 .mcp.json 复制到任何移动项目中——Flutter、React Native、Kotlin、Swift——AI 助手便能在该目录中获得设备超能力。无需全局安装。

免费版与 Pro 版

免费版（14 个工具）——无需许可证密钥

Pro 版（额外提供 35 个工具）——₹499/月

获取 Pro 许可证——解锁全部 49 个工具。付款后，你将在 1 小时内通过电子邮件收到许可证密钥。将其添加到 .mcp.json 中：

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "MOBILE_MCP_LICENSE_KEY": "your-license-key"
      }
    }
  }
}

AI 视觉分析（12 个工具）

使用 AI 视觉（Claude 或 Gemini）理解屏幕上的内容。

Flutter Widget Tree（10 个工具）

通过 Dart VM Service Protocol 连接到正在运行的 Flutter 应用。将每个 Widget 映射到其源代码位置（file:line）。

iOS 模拟器（4 个工具）

仅限 macOS。通过 xcrun simctl 控制 iOS 模拟器。

视频录制（2 个工具）

测试生成（3 个工具）

应用管理（4 个工具）

性能

该服务经过优化，可尽量降低延迟和 AI 令牌开销：

• 四层元素搜索：配套应用（即时）-> 本地文本匹配（<1ms）-> 缓存的 AI -> 新的 AI。smart_tap 比朴素的 AI 调用快 35 倍（205ms 对比 7.6s）。
• 配套应用：基于 AccessibilityService 的 Android 应用可在 105ms 内提供 UI 树（比 UIAutomator 的 2448ms 快 23 倍）。首次使用时自动安装。
• 屏幕截图压缩：AI 工具会自动压缩为 JPEG q=60、400w——体积缩小 89%（251KB -> 28KB），且 AI 质量毫无损失。
• 并行采集：通过 Promise.all() 同时获取屏幕截图和 UI 树。
• TTL 缓存：5 秒缓存可避免高频连续使用工具时重复调用 ADB。

环境变量

架构

src/
|-- index.ts              # CLI entry point (auto-discovery, env config)
|-- server.ts             # MCP server factory
|-- license.ts            # License validation and tier gating
|-- types.ts              # Shared interfaces
|-- drivers/android/      # ADB driver (DeviceDriver implementation)
|   |-- adb.ts            # Low-level ADB command wrapper
|   |-- companion-client.ts # TCP client for companion app
|   +-- index.ts          # AndroidDriver class (4-strategy UI element retrieval)
|-- drivers/flutter/      # Dart VM Service driver
|   |-- index.ts          # FlutterDriver (discovery, inspection, source mapping, hot reload)
|   +-- vm-service.ts     # JSON-RPC 2.0 WebSocket client (DDS redirect handling)
|-- drivers/ios/          # iOS Simulator driver (macOS only)
|   |-- index.ts          # IOSSimulatorDriver via xcrun simctl
|   +-- simctl.ts         # Low-level simctl command wrapper
|-- tools/                # MCP tool registrations (free + pro gating)
|   |-- device-tools.ts   # Device management
|   |-- screen-tools.ts   # Screenshots & UI inspection
|   |-- interaction-tools.ts # Touch, type, keys
|   |-- app-tools.ts      # App management
|   |-- log-tools.ts      # Logcat
|   |-- ai-tools.ts       # AI-powered tools
|   |-- flutter-tools.ts  # Flutter widget inspection
|   |-- ios-tools.ts      # iOS simulator tools
|   |-- video-tools.ts    # Screen recording
|   +-- recording-tools.ts # Test generation
|-- recording/            # Test script generation
|   |-- recorder.ts       # ActionRecorder (records MCP tool calls)
|   +-- generator.ts      # TestGenerator (TypeScript/Python/JSON output)
|-- ai/                   # AI visual analysis engine
|   |-- client.ts         # Multi-provider client (Anthropic + Google)
|   |-- prompts.ts        # System prompts & UI element summarizer
|   |-- analyzer.ts       # ScreenAnalyzer orchestrator (caching, parallel capture)
|   +-- element-search.ts # Local element search (text/alias matching, no AI needed)
+-- utils/
    |-- discovery.ts      # ADB auto-discovery
    +-- image.ts          # PNG parsing, JPEG compression, bilinear resize

companion-app/            # Android companion app (Kotlin)
                          # AccessibilityService + TCP JSON-RPC for fast UI tree

路线图

• 支持 iOS 实体设备
• 多设备编排
• CI/CD 集成
• 支持云端设备农场

测试环境

• 设备：Pixel 8（Android 16）、Samsung Galaxy 系列、Android 模拟器
• 应用：Telegram、Instagram、Spotify、WhatsApp、YouTube、Chrome、Settings 和 Flutter 应用
• AI 提供商：Google Gemini 2.5 Flash、Anthropic Claude
• 平台：Windows 11、macOS（iOS 模拟器）
• 连接方式：USB 和无线 ADB

许可证

Business Source License 1.1

• 个人和非商业用途免费
• 商业用途需购买付费许可证
• 将于 2030 年 3 月 23 日转为 Apache 2.0

完整条款请参阅 LICENSE。