🧭 Three Approaches to Interaction

Pick the approach that matches your target app.

| Approach | Best for | Key tools | |-----------------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------| | Visual (universal)| Any app — games, Qt, custom renderers, anything without an AX tree | take_screenshot, find_text, click, type_text, find_image | | AX Dispatch (macOS — preferred for native macOS apps) | AppKit / SwiftUI apps — System Settings, Finder, Mail, Xcode, Notes | take_ax_snapshot, ax_click, ax_set_value, ax_select | | CDP (Chrome / Electron) | Web content, Electron apps with --remote-debugging-port | cdp_connect, cdp_find_elements, cdp_take_dom_snapshot, cdp_click, cdp_fill |

For macOS native apps, AX Dispatch is the preferred path — it's element-precise, doesn't move the mouse, and doesn't steal focus. See the Native App AX Dispatch recipe.

There's also a fourth, niche path: AppDebugKit (app_connect / app_query / app_click) for apps instrumented with the AppDebugKit library. Mostly useful for developers testing their own apps.

🆚 How it compares

The most honest peers are other MCP servers for computer use. This table compares native-devtools-mcp against the leading MCP servers and two widely used non-MCP libraries.

| Capability | native-devtools-mcp | Playwright MCP | Windows-MCP | Appium | pywinauto | |--------------------------------|:-------------------:|:------------------------:|:----------------------:|:----------------:|:----------------:| | Native macOS apps | ✅ AX + screenshots | ❌ browser only | ❌ Windows only | ❌ mobile focus | ❌ Windows only | | Native Windows apps | ✅ UIA + input | ❌ browser only | ✅ | ◐ limited | ✅ | | Web / DOM automation | ✅ via CDP | ✅ | ◐ via Windows UIA | ◐ mobile-web | ❌ | | Electron apps | ✅ CDP + AX | ✅ first-class _electron| ◐ if UIA exposed | ❌ | ◐ if UIA exposed | | Android devices (ADB) | ✅ built-in | ◐ experimental | ❌ | ✅ first-class | ❌ | | MCP-native | ✅ | ✅ | ✅ | ❌ | ❌ | | Local, no API key | ✅ | ✅ | ✅ | ✅ self-hosted | ✅ |

Where native-devtools-mcp stands out: one local MCP server covering macOS + Windows + Chrome/Electron (CDP) + Android in the same session, plus element-precise macOS AX dispatch that doesn't move the cursor or steal focus.

Honest limits:

• No Linux (contributions welcome — see Linux Desktop MCP for an AT-SPI2-based alternative in the meantime)
• Browser automation is Chrome / Electron only via CDP — no Firefox, no WebKit (for those, use Playwright MCP)
• Headed only — depends on real-machine permissions; not a headless CI test grid
• No iOS

If you need just web automation, Playwright MCP is more mature. If you need just mobile (iOS + Android + deep device features), Appium is more mature. This server is for the cross-cutting native-desktop + Chrome/Electron + Android case.

📦 Installation

The install steps are identical on macOS and Windows.

Option 1: Run with npx (no install needed)

npx -y native-devtools-mcp

Option 2: Global install

npm install -g native-devtools-mcp

Option 3: Build from source (Rust)

Using the build script (clones, builds, and runs setup):

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

Or manually:

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

Manual configuration (without the setup wizard)

macOS — Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json

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

Windows — Claude Desktop

Config file: %APPDATA%\Claude\claude_desktop_config.json

Claude Code, Cursor, and other MCP clients

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

Requires Node.js 18+.

macOS permissions: the server needs Accessibility and Screen Recording permissions. The setup wizard opens the right System Settings panes for you. Without both, clicks silently fail and screenshots return a black rectangle.

Linux is not supported yet. The server uses platform-specific APIs (Core Graphics + Accessibility on macOS, Win32 + UI Automation on Windows) that don't exist on Linux. Contributions welcome — X11/Wayland screenshot, input, and AT-SPI paths would be a good first issue.

🏁 Getting Started

After installing, run the setup wizard:

npx native-devtools-mcp setup

This will:

1. Check permissions (macOS) — verifies Accessibility and Screen Recording, opens System Settings if needed.
2. Detect your MCP clients — finds Claude Desktop, Claude Code, and Cursor.
3. Write the configuration — generates the correct JSON config and offers to write it for you.

Then restart your MCP client and you're ready to go.

Claude Desktop on macOS requires the signed app bundle (Gatekeeper blocks npx). Download NativeDevtools-X.X.X.dmg from GitHub Releases, drag to /Applications, then run setup — it will detect the app and configure Claude Desktop to use it.

VS Code, Windsurf, and other clients: setup doesn't auto-detect these yet. Run setup for the permission checks, then see the manual configuration above for the JSON config snippet.

Claude Code tip: To avoid approving every tool call (clicks, screenshots), add this to .claude/settings.local.json:

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

⚠️ Operational safety

• Hands off: when the agent is "driving" (clicking / typing), don't move your mouse or type. Real hardware inputs conflict with simulated ones and clic