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 代理：閱讀 以瞭解工具定義、工作流模式和機器可讀的使用指南。

特性 • 安裝 • 快速開始 • 使用示例 • 安全與信任 • 針對 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）能夠 輕鬆發現和使用。

• 📄 閱讀 ：這是一份專門為大語言模型設計的緊湊、優化令牌的技術參考文檔，包含意圖定義、架構示例和推理模式。

系統提示的核心功能：

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

該腳本將克隆倉庫，在構建前可選擇打開倉庫進行審查，編譯發佈版二進制文件，並運行設置。詳情請參閱 。

審核代碼

詳細記錄了使用了哪些權限、在源代碼中的位置，幷包含一個可粘貼到任何 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          → 查找設備序列號
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