native-devtools-mcp

🚀 native-devtools-mcp

native-devtools-mcp 是一款适用于 macOS、Windows 和 Android 计算机的模型上下文协议（MCP）服务器。它允许 AI 代理和 MCP 客户端通过截图、OCR、基于无障碍功能的文本查找、输入模拟、窗口管理和 ADB 直接控制原生桌面应用程序和 Android 设备。

当仅靠浏览器自动化无法满足需求时，可使用该工具，例如 Electron 应用程序、系统对话框、桌面工具、原生应用程序测试以及 Android 设备工作流。它可与 Claude Desktop、Claude Code、Cursor 等其他支持 MCP 的客户端配合使用。

该工具适用于基于 MCP 的计算机使用、桌面自动化、UI 自动化、原生应用程序测试、端到端测试、RPA、屏幕阅读、鼠标和键盘控制以及 Android 设备自动化。

npx -y native-devtools-mcp

核心功能

• 截图、OCR 和以无障碍功能优先的 find_text
• click、type_text、scroll、launch_app、quit_app 和窗口管理
• element_at_point，用于检查屏幕坐标处的可访问 UI 元素
• load_image + find_image，用于查找图标和自定义控件等非文本 UI 元素
• 通过 ADB 实现 Android 截图、文本查找、输入和应用程序控制
• 本地执行：截图和输入数据保留在本地机器上

针对 AI 代理：阅读 AGENTS.md 以了解工具定义、工作流模式和机器可读的使用指南。

特性 • 安装 • 快速开始 • 使用示例 • 安全与信任 • 针对 AI 代理 • Android 支持

✨ 主要特性

• 👀 计算机视觉：捕获屏幕、窗口或特定区域的截图。包含内置的 OCR（文本识别）功能，可“读取”屏幕内容。
• 🖱️ 输入模拟：自然地进行点击、拖动、滚动和输入文本操作。支持全局坐标和相对于窗口的操作。
• 🪟 窗口管理：列出打开的窗口、查找应用程序并将其置于焦点位置。
• 🧩 模板匹配：使用 load_image + find_image 查找非文本 UI 元素（图标、形状），并返回精确的点击坐标。
• 🔒 本地与隐私：100% 本地执行。截图和数据不会发送到外部服务器。
• 📱 Android 支持：通过 ADB 连接 Android 设备，实现截图、输入模拟、UI 元素搜索和应用程序管理，所有操作都可通过同一个 MCP 服务器完成。
• 🔍 悬停跟踪：实时跟踪光标在 UI 元素上的悬停转换。可配置的停留阈值过滤器可过滤掉干扰信息，专为大语言模型观察用户导航模式而设计，仅适用于 macOS。
• 🔌 双模式交互：
  1. 视觉/原生模式：通过截图和坐标与 任何 应用程序配合使用（通用）。
  2. AppDebugKit 模式：与支持的应用程序进行深度集成，以检查 UI 树（类似 HTML DOM 结构）。

🤖 针对 AI 代理（大语言模型）

此 MCP 服务器旨在让 AI 模型（Claude、Gemini、GPT）能够 轻松发现和使用。

• 📄 阅读 AGENTS.md：这是一份专门为大语言模型设计的紧凑、优化令牌的技术参考文档，包含意图定义、架构示例和推理模式。

系统提示的核心功能：

1. take_screenshot：充当“眼睛”，返回图像、布局元数据和文本位置（OCR）。
2. click / type_text：充当“手”，根据视觉反馈与系统进行交互。
3. find_text：用于在屏幕上查找文本并立即获取其坐标的快捷方式。使用平台的 无障碍功能 API（macOS 无障碍功能 / Windows UI 自动化）进行精确的元素级匹配，若匹配失败则使用 OCR 作为后备方案。
4. element_at_point：检查给定屏幕坐标处的无障碍元素，返回名称、角色、标签、值、边界、进程 ID 和应用程序名称。注意：注重隐私的 Electron 应用程序（如 Signal）可能会限制其无障碍功能树，仅返回一个容器，此时可使用 take_screenshot 和 OCR 作为后备方案。
5. load_image / find_image：用于非文本 UI 元素（图标、形状）的模板匹配，返回用于点击的屏幕坐标。
6. start_hover_tracking / get_hover_events / stop_hover_tracking：跟踪光标在 UI 元素上的悬停转换。可配置停留阈值过滤器。仅适用于 macOS。
7. launch_app / quit_app：使用可选的命令行参数启动应用程序，或正常/强制退出应用程序。

📦 安装指南

macOS 和 Windows 的安装步骤相同。

选项 1：使用 npx 运行（无需安装）

npx -y native-devtools-mcp

选项 2：全局安装

npm install -g native-devtools-mcp

选项 3：从源代码构建（Rust）

curl -fsSL https://raw.githubusercontent.com/sh3ll3x3c/native-devtools-mcp/master/scripts/build-from-source.sh | bash

git clone https://github.com/sh3ll3x3c/native-devtools-mcp
cd native-devtools-mcp
cargo build --release
# 二进制文件：./target/release/native-devtools-mcp

🚀 快速开始

安装完成后，运行设置向导：

npx native-devtools-mcp setup

这将执行以下操作：

1. 检查权限（macOS）：验证无障碍功能和屏幕录制权限，如有需要将打开系统设置。
2. 检测 MCP 客户端：查找 Claude Desktop、Claude Code、Cursor。
3. 写入配置：生成正确的 JSON 配置文件，并提供为你写入的选项。

然后重启 MCP 客户端即可开始使用。

macOS 上的 Claude Desktop 需要已签名的应用程序包（Gatekeeper 会阻止 npx）。从 GitHub 发布页面 下载 NativeDevtools-X.X.X.dmg，将其拖到 /Applications 目录，然后运行设置，它将检测到该应用程序并配置 Claude Desktop 使用它。

VS Code、Windsurf 和其他客户端：setup 目前还不能自动检测这些客户端。运行 setup 进行权限检查，然后参考下面的手动配置获取 JSON 配置片段。

Claude Code 提示：为避免每次工具调用（点击、截图）都需要批准，可将以下内容添加到 .claude/settings.local.json 文件中：

{ "permissions": { "allow": ["mcp__native-devtools__*"] } }

💻 使用示例和案例

• 使用示例和案例索引
• Claude Desktop 设置
• Claude Code 设置
• Cursor 设置
• 端到端桌面流程
• 原生应用程序点击流程
• OCR 后备方案和元素检查
• 模板匹配流程
• Android 快速入门

{
  "mcpServers": {
    "native-devtools": {
      "command": "/Applications/NativeDevtools.app/Contents/MacOS/native-devtools-mcp"
    }
  }
}

{
  "mcpServers": {
    "native-devtools": {
      "command": "npx",
      "args": ["-y", "native-devtools-mcp"]
    }
  }
}

🔐 安全与信任

此工具需要无障碍功能和屏幕录制权限，这需要很大的信任。以下是验证其是否值得信任的方法。

验证二进制文件

native-devtools-mcp verify

计算正在运行的二进制文件的 SHA-256 哈希值，并将其与 GitHub 发布页面 上发布的官方校验和进行比较。如果哈希值匹配，则表示你运行的是未修改的官方版本。

从源代码构建

如果你不信任预构建的二进制文件，可以自己构建：

curl -fsSL https://raw.githubusercontent.com/sh3ll3x3c/native-devtools-mcp/master/scripts/build-from-source.sh | bash

该脚本将克隆仓库，在构建前可选择打开仓库进行审查，编译发布版二进制文件，并运行设置。详情请参阅 scripts/build-from-source.sh。

审核代码

SECURITY_AUDIT.md 详细记录了使用了哪些权限、在源代码中的位置，并包含一个可粘贴到任何 AI 模型中的大语言模型审核提示，用于进行独立的安全审查。

此服务器不会做的事情

• 无未经请求的网络访问：服务器不会主动连接到外部网络。仅当 MCP 客户端显式调用 app_connect（通过 WebSocket 连接到本地调试服务器）或运行 verify 子命令（从 GitHub 获取校验和）时才会使用网络。
• 无文件扫描：不会读取或索引你的文件。唯一的文件读取操作是 load_image（读取 MCP 客户端显式提供的路径）和用于截图的临时文件（截图捕获后立即删除）。
• 无后台持久化：当 MCP 客户端断开连接时，服务器将退出。
• 无数据泄露：截图通过标准输出返回给 MCP 客户端，不会存储或传输到其他地方。

🔍 两种交互方式

我们提供两种方式供代理进行交互，以便它们可以选择最适合的工具。

1. “视觉”方式（通用）

适用场景：适用于 99% 的应用程序（Electron、Qt、游戏、浏览器）。

• 工作原理：代理获取截图，进行视觉分析（或使用 OCR），并在指定坐标处点击。
• 工具：take_screenshot、find_text、click、type_text（以及用于图标和形状的 load_image / find_image）。
• 示例：“点击看起来像齿轮图标的按钮” → 使用 find_image 和齿轮模板。

2. “结构”方式（AppDebugKit）

适用场景：适用于使用我们的 AppDebugKit 库进行专门检测的应用程序（主要用于开发人员测试自己的应用程序）。

• 工作原理：代理连接到调试端口并查询 UI 树（类似于 HTML DOM）。
• 工具：app_connect、app_query、app_click。
• 示例：app_click(element_id="submit-button")。

🧩 模板匹配（find_image）

当目标不是文本（图标、开关、自定义控件）且 OCR 或 find_text 无法识别时，可使用 find_image。

典型流程：

1. take_screenshot(app_name="MyApp") → screenshot_id
2. load_image(path="/path/to/icon.png") → template_id
3. find_image(screenshot_id="...", template_id="...") → matches 包含 screen_x/screen_y
4. click(x=..., y=...)

快速与精确模式：

• 快速模式（默认）：使用降采样和提前退出机制以提高速度。
• 精确模式：使用全分辨率、更广泛的缩放搜索和较小的步长进行全面匹配。

可选输入（如 mask_id、search_region、scales 和 rotations）可以提高精度和性能。

📱 Android 支持

该工具内置了 Android 支持。MCP 服务器通过 ADB（USB 或 Wi-Fi）与 Android 设备进行通信，提供截图、输入模拟、UI 元素搜索和应用程序管理功能。

前提条件

1. 主机上安装 ADB（在 macOS 上可使用 brew install android-platform-tools，或通过 Android SDK 进行安装）
2. Android 设备启用 USB 调试（设置 > 开发者选项 > USB 调试）
3. ADB 服务器正在运行 — 运行 adb devices 时会自动启动

Android 工具

所有 Android 工具都以 android_ 开头，连接到设备后会动态显示：

| 工具 | 描述 | |------|-------------| | android_list_devices | 列出所有通过 ADB 连接的设备（始终可用） | | android_connect | 通过序列号连接到设备 | | android_disconnect | 断开与当前设备的连接 | | android_screenshot | 捕获设备屏幕截图 | | android_find_text | 通过文本查找 UI 元素（通过 uiautomator） | | android_click | 在屏幕坐标处点击 | | android_swipe | 在两点之间滑动 | | android_type_text | 在设备上输入文本 | | android_press_key | 按下按键（如 KEYCODE_HOME、KEYCODE_BACK） | | android_launch_app | 通过包名启动应用程序 | | android_list_apps | 列出已安装的应用程序包 | | android_get_display_info | 获取屏幕分辨率和密度 | | android_get_current_activity | 获取当前前台活动 |

典型工作流程

android_list_devices          → 查找设备序列号
android_connect(serial="...")  → 连接设备（解锁 android_* 工具）
android_screenshot            → 查看屏幕内容
android_find_text(text="OK")  → 定位按钮
android_click(x=..., y=...)   → 点击按钮

已知问题

MIUI / HyperOS（小米、红米、POCO 设备）：输入注入（android_click、android_type_text、android_press_key、android_swipe）和 android_find_text（通过 uiautomator）需要额外的安全开关：

设置 > 开发者选项 > USB 调试（安全设置） — 启用此开关。MIUI 可能需要你使用小米账户登录才能启用该开关。

如果不启用此开关，输入工具会出现 INJECT_EVENTS permission 错误，android_find_text 会出现 could not get idle state 错误。截图和设备信息工具无需此开关即可正常工作。

无线 ADB：若要在不使用 USB 电缆的情况下连接设备，首先通过 USB 连接并运行：

adb tcpip 5555
adb connect <phone-ip>:5555

然后在 android_connect 中使用 <phone-ip>:5555 作为序列号。

冒烟测试

冒烟测试用于验证所有 Android 工具是否能在真实连接的设备上正常工作。默认情况下，这些测试被标记为 #[ignore]，必须显式运行：

cargo test --test android_smoke_tests -- --ignored --test-threads=1

测试必须按顺序运行（--test-threads=1），因为它们共享同一个物理设备。设备必须处于解锁和唤醒状态。

🔧 技术细节

graph TD
    Client[Claude / 大语言模型客户端] <-->|JSON-RPC 2.0| Server[native-devtools-mcp]
    Server -->|直接 API| Sys[系统 API]
    Server -->|WebSocket| Debug[AppDebugKit]
    Server -->|ADB 协议| Android[Android 设备]

    subgraph "你的机器"
        Sys -->|屏幕/OCR| macOS[CoreGraphics / Vision]
        Sys -->|输入| Win[Win32 / SendInput]
        Sys -->|文本搜索| UIA[UI 自动化]
        Debug -.->|检查| App[目标应用程序]
    end

    subgraph "Android 设备（USB/Wi-Fi）"
        Android -->|屏幕截图| Screen[屏幕截图]
        Android -->|输入| Input[点击 / 滑动 / 输入]
        Android -->|uiautomator| UITree[UI 层次结构]
    end

screen_x = screenshot_origin_x + (pixel_x / screenshot_scale)
screen_y = screenshot_origin_y + (pixel_y / screenshot_scale)

⚠️ 操作安全

• 请勿干预：当代理正在“操作”（点击/输入）时，请勿移动鼠标或输入。
  • 原因：真实的硬件输入可能会与模拟输入冲突，导致点击位置错误。
• 聚焦很重要：确保你希望代理使用的窗口可见。如果弹出窗口抢占了焦点，代理可能会在未检查的情况下将输入发送到错误的窗口。

🪟 Windows 注意事项

该工具在 Windows 10/11 上可直接使用。

• 使用标准的 Win32 API（GDI、SendInput）。
• find_text 使用 UI 自动化（UIA） 作为主要搜索机制，查询无障碍功能树中的元素名称。这与 macOS 上使用的以无障碍功能优先的方法相同（使用 Accessibility API）。当 UIA 未找到匹配项时，会自动使用 OCR 作为后备方案。
• OCR 使用内置的 Windows 媒体 OCR 引擎（离线）。
• 注意：除非 MCP 服务器本身以管理员身份运行，否则无法与“以管理员身份运行”的窗口进行交互。

📄 许可证

MIT © sh3ll3x3c