Native DevTools

native-devtools-mcp

一款用于操作原生桌面和移动应用的 MCP 服务，支持 macOS、Windows、Android，以及通过 CDP 连接 Chrome/Electron。

一键添加到客户端：

Claude Code： claude mcp add native-devtools -- npx -y native-devtools-mcp

native-devtools-mcp 让 AI Agent 和 MCP 客户端直接操作原生桌面应用、Chrome/Electron 浏览器和 Android 设备，提供截图、OCR、无障碍优先的元素查找、输入模拟、窗口管理、Chrome DevTools Protocol（CDP）和 ADB，全部集成在一个本地服务中。兼容 Claude Desktop、Claude Code、Cursor 及其他兼容 MCP 的客户端。

快速开始

npx -y native-devtools-mcp

macOS	Windows

🚀 功能

• 👀 计算机视觉： 截取屏幕、窗口或区域的截图，并内置 OCR（macOS 上使用 Vision，Windows 上使用 Windows Media OCR）。
• 🖱️ 输入模拟： 点击、拖动、滚动、输入文字，支持全局坐标、相对于窗口的坐标，以及相对于截图的定位。
• 🎯 精确到元素的 AX 调度（macOS）： take_ax_snapshot → ax_click / ax_set_value / ax_select——直接对无障碍树中的元素执行操作，无需移动鼠标或抢占焦点。这是操作原生 macOS 应用的首选方式。
• 🌐 浏览器自动化（CDP）： 通过 Chrome DevTools Protocol 操作 Chrome 和 Electron 应用（Signal、Discord、VS Code、Slack），支持 DOM 级点击、填充、导航和 JS 求值，无需单独的 Node.js 服务。
• 📱 Android（ADB）： 通过 USB 或 Wi-Fi 提供截图、基于 uiautomator 的文本查找、输入和应用管理。
• 🧩 模板匹配： 使用 load_image + find_image 查找 OCR 无法识别的图标、开关和自定义控件。
• 🪟 窗口管理： 列出、聚焦、启动和退出应用；将窗口录制为带时间戳的 JPEG 帧。
• 🔍 悬停跟踪： 通过根据悬停时长筛选的事件观察用户的导航模式，专为观察用户工作过程的大模型设计。
• 🔒 本地且私密： 100% 在本地执行。截图和输入不会离开你的设备。

🧭 三种交互方式

选择适合目标应用的方式。

对于 macOS 原生应用，AX Dispatch 是首选方式 — 它能精确定位元素，不会移动鼠标，也不会抢占焦点。请参阅原生应用 AX Dispatch 方案。

还有第四种小众方式：AppDebugKit（app_connect / app_query / app_click），适用于使用 AppDebugKit 库进行插桩的应用。它主要适用于开发者测试自己的应用。

🆚 对比

最直接的对比对象是其他用于计算机操作的 MCP 服务。下表将 native-devtools-mcp 与领先的 MCP 服务以及两个广泛使用的非 MCP 库进行了比较。

native-devtools-mcp 的突出优势： 一个本地 MCP 服务即可在同一会话中覆盖 macOS + Windows + Chrome/Electron（CDP）+ Android，此外还支持精准定位元素的 macOS AX 操作分发，不会移动光标或窃取焦点。

客观限制：

• 不支持 Linux（欢迎贡献——目前可参阅 Linux Desktop MCP，这是基于 AT-SPI2 的替代方案）
• 浏览器自动化仅支持 Chrome / Electron，通过 CDP 实现——不支持 Firefox 和 WebKit（如需使用这些浏览器，请用 Playwright MCP）
• 仅支持有界面模式——依赖真实机器权限；并非无头 CI 测试网格
• 不支持 iOS

如果你只需要 Web 自动化，Playwright MCP 更成熟。如果你只需要移动端（iOS + Android + 深度设备功能），Appium 更成熟。本服务适用于跨平台原生桌面 + Chrome/Electron + Android 场景。

📦 安装

macOS 和 Windows 上的安装步骤相同。

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

npx -y native-devtools-mcp

选项 2：全局安装

npm install -g native-devtools-mcp

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

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

git clone https://github.com/vectora-foundry/native-devtools-mcp
cd native-devtools-mcp
cargo build --release
# Binary: ./target/release/native-devtools-mcp

手动配置（不使用设置向导）

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

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

macOS 权限：服务需要辅助功能和屏幕录制权限。设置向导会为你打开相应的系统设置面板。缺少任一权限时，点击操作会静默失败，截图则会返回黑色矩形。

**目前尚不支持 Linux。**本服务使用 Linux 上不存在的平台专属 API（macOS 上的 Core Graphics + 辅助功能，Windows 上的 Win32 + UI Automation）。欢迎贡献——X11/Wayland 截图、输入和 AT-SPI 路径都是不错的入门任务。

🏁 开始使用

安装后，运行设置向导：

npx native-devtools-mcp setup

向导将：

1. 检查权限（macOS）——验证辅助功能和屏幕录制权限，并在需要时打开系统设置。
2. 检测 MCP 客户端——查找 Claude Desktop、Claude Code 和 Cursor。
3. 写入配置——生成正确的 JSON 配置，并提供代为写入的选项。

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

macOS 上的 Claude Desktop 需要使用经过签名的应用程序包（Gatekeeper 会阻止 npx）。从 GitHub Releases 下载 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__*"] } }

⚠️ 操作安全

• 不要触碰设备： Agent 正在“操作”时（点击／输入），不要移动鼠标或打字。真实硬件输入会与模拟输入冲突，导致点击落在错误的位置。
• 注意焦点： 确保要让 Agent 操作的窗口处于可见状态。如果弹出窗口在流程中途抢占焦点，Agent 可能会在未重新检查的情况下向错误的窗口输入内容。
• 在 macOS 上优先使用 AX Dispatch：如果你想继续使用设备，请使用 AX 调用——它们不会移动光标，也不会抢占当前活动窗口的焦点。

📚 配方与示例

• 配方索引
• Claude Desktop 设置 · Claude Code 设置 · Cursor 设置
• 端到端桌面工作流
• 原生应用 AX Dispatch 工作流（macOS） — 原生 macOS 应用首选
• 原生应用点击工作流
• OCR 后备方案与元素检查
• 模板匹配工作流
• Android 快速入门

🌐 浏览器自动化（CDP）

通过 Chrome DevTools Protocol 连接 Chrome 或 Electron 应用，实现 DOM 级自动化——对于网页内容，这比基于坐标的点击更加可靠。

# Launch Chrome with remote debugging
launch_app(app_name="Google Chrome", args=["--remote-debugging-port=9222", "--user-data-dir=/tmp/chrome-profile"])

# Connect and automate
cdp_connect(port=9222)
cdp_navigate(url="https://example.com")
cdp_find_elements(query="search")    # DOM walker with element UIDs (d1, d2, ...)
cdp_fill(uid="d1", value="search query")
cdp_press_key(key="Enter")
cdp_wait_for(text=["Results"])

21 个 CDP 工具——页面摘要、DOM 快照、查找元素、元素上下文、点击、悬停、填充、输入、按键、导航、处理对话框、管理标签页、等待文本或页面变化、执行 JS、元素检查等。CDP 工具始终会列出；在 cdp_connect 成功之前，调用它们会返回“No CDP connection”错误。适用于 Chrome 136+、Chromium 和 Electron 应用（Signal、Discord、VS Code、Slack）。完整工具参考请参阅 AGENTS.md。

Chrome 136+ 注意事项： 必须将 --user-data-dir=<path> 与 --remote-debugging-port 一同使用——Chrome 在使用默认配置文件时会静默忽略调试端口。Electron 应用只需使用 --remote-debugging-port。

📱 Android 支持

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

前置条件

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

工具

所有 Android 工具均以 android_ 为前缀。android_list_devices 和 android_connect 始终可用；连接到设备后，其他工具会动态显示：

典型工作流

android_list_devices           → find your device serial
android_connect(serial="...")  → connect (unlocks android_* tools)
android_screenshot             → see what's on screen
android_find_text(text="OK")   → locate a button
android_click(x=..., y=...)    → tap it

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

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

🔐 安全与信任

此工具需要无障碍和屏幕录制权限——这需要相当程度的信任。以下是验证它是否值得信任的方法。

验证二进制文件

native-devtools-mcp verify

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

审查代码

SECURITY_AUDIT.md 准确记录了使用了哪些权限、它们在源代码中的位置，并提供了一段 LLM 审计提示词，你可以将其粘贴到任意 AI 模型中进行独立安全审查。

此服务不会做什么

• **不会擅自访问网络。**此服务绝不会主动联系外部服务器。只有在 MCP 客户端明确调用 app_connect 时（通过 WebSocket 连接本地调试服务），或你运行 verify 子命令时（从 GitHub 获取校验和），才会使用网络。
• **不会扫描文件。**不会读取或索引你的文件。只会读取 load_image 指定的文件（由 MCP 客户端明确提供路径），以及用于截屏的短期临时文件（截屏后立即删除）。
• **不会在后台持久运行。**MCP 客户端断开连接后即退出。
• **不会外传数据。**截屏会通过 stdout 返回给 MCP 客户端，不会存储或传输到其他位置。

❓ 常见问题

能在 Linux 上运行吗？ 目前还不行——仅支持 macOS、Windows 和 Android。该服务在 macOS 上使用 Core Graphics + Accessibility API，在 Windows 上使用 Win32 + UI Automation。欢迎贡献 X11/Wayland + AT-SPI 移植版本。

需要 API 密钥吗？ 不需要。该服务完全在本地运行，不会发出任何外部 API 调用。你的 MCP 客户端可能需要自己的大模型 API 密钥（Anthropic、OpenAI 等），但该服务本身不需要。

这与 Claude Computer Use 有什么不同？ Claude Computer Use 是一款 Anthropic API beta 工具，需要通过 beta 标头配合 Claude Opus、Sonnet 和 Haiku 使用，并且需要 Anthropic API 密钥。它通过屏幕截图和基于坐标的鼠标／键盘操作来运行。native-devtools-mcp 与模型无关（任何支持 MCP 的模型均可），完全在本地运行，不依赖 API，并且额外支持精准定位元素的 macOS AX 操作、Chrome DevTools Protocol，以及通过 ADB 操作 Android。

能与本地模型（Ollama、LM Studio 等）配合使用吗？ 可以——只要客户端支持 MCP 即可。任何兼容 MCP 的客户端都可以连接。不支持 MCP 的客户端可以通过桥接程序调用该服务。

它免费／开源吗？ 是的，采用 MIT 许可证。请参阅 LICENSE。

它会记录我的操作吗？ 不会——除非你明确调用 start_recording，将录制内容写入你指定的目录，并在调用 stop_recording 时停止。悬停跟踪同样只会在 start_hover_tracking 运行期间启用。除此之外，不会录制或发送任何内容。

它与 Playwright 或 Playwright MCP 相比如何？ Playwright 是专用于 Web 自动化的成熟方案，支持 Chromium、Firefox 和 WebKit，并通过 _electron.launch() 提供一流的 Electron 支持，还支持实验性的 Android 自动化。Playwright MCP 将其封装为供 AI Agent 使用的 MCP 服务。如果你只需要 Web／Electron 自动化，请使用 Playwright MCP。除了 Chrome／Electron，native-devtools-mcp 还支持 macOS／Windows 原生应用和 Android 设备，并通过一个本地 MCP 服务提供这些功能——Playwright MCP 则不支持。

🏗️ 架构

graph TD
    Client[Claude / LLM Client] <-->|JSON-RPC 2.0| Server[native-devtools-mcp]
    Server -->|Direct API| Sys[System APIs]
    Server -->|CDP / WebSocket| Chrome[Chrome / Electron]
    Server -->|WebSocket| Debug[AppDebugKit]
    Server -->|ADB Protocol| Android[Android Device]

    subgraph "Your Machine"
        Sys -->|Screen/OCR| macOS[CoreGraphics / Vision]
        Sys -->|Input| Win[Win32 / SendInput]
        Sys -->|Text Search| UIA[UI Automation]
        Sys -->|AX Snapshot + Dispatch| AXapi[Accessibility API - macOS]
        Chrome -.->|DOM-level| ChromeApp[Web Page / Electron UI]
        Debug -.->|Inspect| App[Instrumented App]
    end

    subgraph "Android Device (USB/Wi-Fi)"
        Android -->|screencap| Screen[Screenshots]
        Android -->|input| Input[Tap / Swipe / Type]
        Android -->|uiautomator| UITree[UI Hierarchy]
    end

截图包含用于准确转换坐标的元数据：

• screenshot_origin_x/y：捕获区域的屏幕空间原点（以点为单位）
• screenshot_scale：显示缩放系数（例如，Retina 显示屏为 2.0）
• screenshot_pixel_width/height：图像的实际像素尺寸
• screenshot_window_id：窗口 ID（用于窗口捕获）

坐标转换：

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

实现说明：

• 窗口捕获（macOS）：使用 screencapture -o 排除窗口阴影。捕获尺寸与 kCGWindowBounds × scale 完全一致，因此根据截图计算出的点击坐标会落在预期的 UI 元素上。
• **区域捕获：**原点坐标会对齐到整数，以匹配实际捕获区域。

🪟 Windows 说明

在 Windows 10/11 上开箱即用。

• 使用标准 Win32 API（GDI、SendInput）。
• find_text 主要使用 UI Automation（UIA） 作为搜索机制，通过查询无障碍树查找元素名称。这与 macOS 上采用的无障碍优先方法相同。如果 UIA 未找到匹配项，会自动回退到 OCR。
• OCR 使用 Windows 内置的 Media OCR 引擎（离线运行）。
• 无法与“以管理员身份运行”的窗口交互，除非 MCP 服务本身也以管理员身份运行。
• 屏幕录制使用 GDI/BitBlt，帧率可配置（默认 5）。如需更高帧率或游戏捕获，DXGI Desktop Duplication API 可提供硬件加速捕获，这是计划中的未来升级。

🤖 面向 AI Agent

面向 Agent 的用法——意图定义、架构示例、推理模式——详见 AGENTS.md。它是一份简洁、经过 Token 优化的参考文档，专为大模型（Claude、Gemini、GPT、本地模型）读取而设计。如果你是 AI Agent，正在阅读此 README 以判断是否使用此服务，请接着阅读该文档。

⭐ Star 历史

📜 许可证

MIT © sh3ll3x3c