{ "target": { "app": "Safari" } } ``` Captures Safari's window even if it's behind other windows. Your foreground stays untouched. ### Background click in a window ```json { "x": 100, "y": 200, "target": { "app": "Safari", "title": "GitHub" } } ``` Clicks at position (100, 200) relative to the Safari window titled "GitHub". No focus change. ### Background text input ```json { "text": "hello world", "target": { "app": "Notes" } } ``` Types into Notes via clipboard paste (CGEvent Cmd+V). Clipboard is saved and restored. ### Compressed screenshot (default behavior in v3.1) ```json { "target": { "app": "Chrome" } } ``` Returns a 1280px-wide JPEG (~150KB) instead of a raw PNG (~5MB). Works out of the box. ### High-res screenshot with no compression ```json { "target": { "app": "Chrome" }, "compression": "none" } ``` Returns the raw PNG — same as v3.0 behavior. ### Custom compression ```json { "target": { "app": "Chrome" }, "compression": "low", "maxWidth": 1920, "quality": 90 } ``` Explicit `maxWidth`/`quality`/`format` override the preset values. ### Tile mode for full-resolution inspection ```json { "target": { "app": "Chrome" }, "tile": { "rows": 2, "cols": 2 } } ``` Returns a manifest with tile metadata. Then fetch individual tiles: ```json { "id": "tiles-1711929600000-abc123", "index": 0, "compression": "medium" } ``` ### Focus-safe foreground operation ```json { "text": "hello", "app": "TextEdit", "mode": "direct" } ``` Writes text directly via AppleScript — bypasses input method entirely. ## Prerequisites - macOS (tested on Sequoia 15.x and Tahoe 26.x) - Node.js 18+ - [cliclick](https://github.com/BlueM/cliclick): `brew install cliclick` - **Accessibility permission** for your terminal app - Optional: Xcode (for iOS simulator tools) - Optional: Android SDK with adb (for Android emulator tools) ## Client Configuration Uses **stdio transport**. Configuration is the same across all MCP clients.

Claude Code

```bash # Project scope claude mcp add macos-desktop-control -- node /path/to/macos-desktop-control/src/index.js # Global scope claude mcp add macos-desktop-control -s user -- node /path/to/macos-desktop-control/src/index.js ```

Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "macos-desktop-control": { "command": "node", "args": ["/path/to/macos-desktop-control/src/index.js"] } } }

macos-desktop-control

Installation