Native Devtools MCP

🚀 native-devtools-mcp

native-devtools-mcp は、macOS、Windows、Androidで使用できるコンピュータ用のモデルコンテキストプロトコル（MCP）サーバーです。スクリーンショット、OCR、アクセシビリティベースのテキスト検索、入力シミュレーション、ウィンドウ管理、ADBを通じて、AIエージェントとMCPクライアントがネイティブデスクトップアプリと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、ウィンドウ管理
• 画面座標でアクセシビリティのあるUI要素を調査する element_at_point
• アイコンやカスタムコントロールなどの非テキストUI要素を見つける load_image + find_image
• Androidのスクリーンショット、テキスト検索、入力、ADBを介したアプリ制御
• ローカル実行：スクリーンショットと入力はマシン上に留まります

AIエージェント向け：ツールの定義、ワークフローパターン、機械可読な使用ガイダンスについては、 を読んでください。

機能 • インストール • クイックスタート • レシピとサンプル • セキュリティと信頼性 • AIエージェント向け • Android

✨ 主な機能

• 👀 コンピュータビジョン：画面、ウィンドウ、または特定の領域のスクリーンショットを撮影します。組み込みのOCR（テキスト認識）を備え、画面を「読み取る」ことができます。
• 🖱️ 入力シミュレーション：自然にクリック、ドラッグ、スクロール、テキスト入力ができます。グローバル座標とウィンドウ相対的なアクションをサポートします。
• 🪟 ウィンドウ管理：開いているウィンドウを一覧表示し、アプリケーションを検索し、フォーカスを移すことができます。
• 🧩 テンプレートマッチング：load_image + find_image を使用して非テキストUI要素（アイコン、形状）を見つけ、正確なクリック座標を返します。
• 🔒 ローカルかつプライベート：100%ローカルで実行されます。スクリーンショットやデータは外部サーバーに送信されることはありません。
• 📱 Androidサポート：ADBを介してAndroidデバイスに接続し、スクリーンショット、入力シミュレーション、UI要素の検索、アプリ管理を同じMCPサーバーから行うことができます。
• 🔍 ホバー追跡：UI要素間のカーソルのホバー遷移をリアルタイムで追跡します。設定可能な滞留しきい値フィルターでノイズを除去します。macOSのみ対応。
• 🔌 デュアルモードインタラクション：
  1. ビジュアル/ネイティブ：スクリーンショットと座標を介して すべての アプリで動作します（汎用）。
  2. AppDebugKit：サポートされているアプリに対してUIツリー（DOMのような構造）を調査するための深い統合。

🤖 AIエージェント（LLM）向け

このMCPサーバーは、AIモデル（Claude、Gemini、GPT）による 高度な発見性と使いやすさ を目的として設計されています。

• 📄 ：LLMによる取り込みに特化した、コンパクトでトークン最適化された技術リファレンスです。意図の定義、スキーマの例、推論パターンが含まれています。

システムプロンプトの主要機能：

1. take_screenshot：「目」の役割を果たします。画像 + レイアウトメタデータ + テキストの位置（OCR）を返します。
2. click / type_text：「手」の役割を果たします。視覚的なフィードバックに基づいてシステムと対話します。
3. find_text：画面上のテキストを見つけ、その座標をすぐに取得するためのショートカットです。プラットフォームの アクセシビリティAPI（macOSアクセシビリティ / Windows UIオートメーション）を使用して正確な要素レベルのマッチングを行い、OCRをフォールバックとして使用します。
4. element_at_point：指定された画面座標のアクセシビリティ要素を調査します。名前、ロール、ラベル、値、境界、PID、アプリ名を返します。注意：プライバシー重視のElectronアプリ（例：Signal）はAXツリーを制限する場合があり、コンテナのみを返すことがあります。この場合は、OCR付きの take_screenshot をフォールバックとして使用してください。
5. load_image / find_image：非テキストUI要素（アイコン、形状）のテンプレートマッチングを行い、クリックするための画面座標を返します。
6. start_hover_tracking / get_hover_events / stop_hover_tracking：UI要素間のカーソルのホバー遷移を追跡します。設定可能な滞留しきい値フィルターがノイズを除去します。macOSのみ対応。
7. launch_app / quit_app：オプションのCLI引数でアプリを起動したり、正常にまたは強制的に終了したりします。

📦 インストール

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 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__*"] } }

📚 レシピとサンプル

• レシピとサンプルの索引
• 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 Releases ページに公開されている公式のチェックサムと照合します。ハッシュが一致すれば、変更されていない公式ビルドを実行していることになります。

ソースからビルドする

事前にビルドされたバイナリを信頼できない場合は、自分でビルドしてください：

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

このスクリプトはリポジトリをクローンし、ビルド前に必要に応じてレビュー用に開き、リリースバイナリをコンパイルし、セットアップを実行します。詳細は を参照してください。

コードを監査する

には、どの権限がどこのソースコードで使用されているかが正確に記載されており、独立したセキュリティレビューを行うために任意のAIモデルに貼り付けることができるLLM監査プロンプトが含まれています。

このサーバーが行わないこと

• 不要なネットワークアクセスは行わない — サーバーは決して外部に接続しません。ネットワークは、MCPクライアントが明示的に app_connect を呼び出した場合（ローカルデバッグサーバーへのWebSocket）、または verify サブコマンドを実行した場合（GitHubからチェックサムを取得）にのみ使用されます。
• ファイルスキャンは行わない — ファイルを読み取ったりインデックスを作成したりしません。唯一のファイル読み取りは load_image（MCPクライアントが明示的に指定したパスを読み取る）とスクリーンショット用の一時ファイル（キャプチャ直後に削除）です。
• バックグラウンドでの永続化は行わない — MCPクライアントが切断されると終了します。
• データの外部流出は行わない — スクリーンショットはstdoutを介してMCPクライアントに返され、他の場所に保存または送信されることはありません。

🔍 2つのインタラクション方法

エージェントがインタラクションするための2つの方法を提供しており、仕事に最適なツールを選択できます。

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（Xiaomi、Redmi、POCOデバイス）：入力注入（android_click、android_type_text、android_press_key、android_swipe）と android_find_text（uiautomatorを介して）には、追加のセキュリティトグルが必要です：

設定 > 開発者オプション > USBデバッグ（セキュリティ設定） — このトグルを有効にします。MIUIでは、これを有効にするにはMiアカウントでサインインする必要がある場合があります。

これを行わないと、入力ツールで 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 / LLM Client] <-->|JSON-RPC 2.0| Server[native-devtools-mcp]
    Server -->|Direct API| Sys[System APIs]
    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]
        Debug -.->|Inspect| App[Target App]
    end

    subgraph "Android Device (USB/Wi-Fi)"
        Android -->|screencap| Screen[Screenshots]
        Android -->|input| Input[Tap / Swipe / Type]
        Android -->|uiautomator| UITree[UI Hierarchy]
    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 Automation（UIA） を主要な検索メカニズムとして使用し、アクセシビリティツリーから要素名をクエリします。これはmacOSで使用されるアクセシビリティ優先のアプローチ（アクセシビリティAPIを使用）と同じです。UIAで一致するものが見つからない場合は、自動的にOCRにフォールバックします。
• OCRは組み込みのWindows Media OCRエンジン（オフライン）を使用します。
• 注意：MCPサーバーが管理者として実行されていない限り、「管理者として実行」のウィンドウとは対話できません。

📄 ライセンス

MIT © sh3ll3x3c