{
"markdown": "\n\n# mac-use-mcp\n\n\n\n> [!WARNING]\n> **This tool has full control over mouse, keyboard, and screen.** Please use in a sandboxed environment to protect your privacy and avoid accidental data loss by your agents. You are responsible for any actions performed through this tool.\n\nZero-native-dependency macOS desktop automation via MCP.\n\nGive AI agents eyes and hands on macOS — click, type, screenshot, and inspect any application.\n\n[](https://github.com/antbotlab/mac-use-mcp/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/mac-use-mcp)\n[](https://www.npmjs.com/package/mac-use-mcp)\n[](./LICENSE)\n[](https://www.typescriptlang.org/)\n\n\n\n## Use Cases\n\n- **Automated UI testing** — click buttons, verify element states with `get_ui_elements`, validate screen content via `screenshot`\n- **Desktop workflow automation** — launch apps with `open_application`, fill forms with `type_text`, navigate menus via `click_menu`\n- **Screenshot-based monitoring** — capture screen regions periodically with `screenshot` for visual diffing or alerting\n- **Accessibility inspection** — query UI element trees with `get_ui_elements` for QA and compliance checks\n- **AI agent computer use** — give LLMs eyes and hands on macOS via `screenshot`, `click`, `type_text`, and more\n\n## Why mac-use-mcp?\n\n- **Just works** — `npx mac-use-mcp` and grant two macOS permissions. No node-gyp, no Xcode tools, no build step.\n- **18 tools, one server** — screenshots, clicks, keystrokes, window management, accessibility inspection, and clipboard.\n- **macOS 13+ on Intel and Apple Silicon** — no native addons, no architecture headaches.\n\n## Install\n\n**Requirements:** macOS 13+ and Node.js 22+. The server communicates over **stdio** transport.\n\n> This package only works on macOS. It will refuse to install on other operating systems.\n\nNo build steps. No native dependencies. Just run:\n\n```bash\nnpx mac-use-mcp\n```\n\n> `npx` will prompt to install the package on first run. Use `npx -y mac-use-mcp` to skip the confirmation.\n\n> [!TIP]\n> **Model selection matters.** Desktop automation involves screenshot–action loops that add up in token usage. A fast model with solid reasoning, good vision, and reliable tool calling is recommended:\n>\n> | Model | Provider |\n> |-------|----------|\n> | Gemini 3 Flash | Google |\n> | Claude Sonnet 4.6 | Anthropic |\n> | GPT-5 mini | OpenAI |\n> | MiniMax-M2.5 | MiniMax |\n> | Kimi K2.5 | Moonshot AI |\n> | Qwen3.5 | Alibaba |\n> | GLM-4.7 | Zhipu AI |\n\n## Permission Setup\n\nmac-use-mcp requires two macOS permissions to function. Grant them once and you're set.\n\n### Accessibility\n\nRequired for mouse and keyboard control.\n\n1. Open **System Settings** > **Privacy & Security** > **Accessibility**\n2. Click the **+** button\n3. Add your MCP client application (e.g., Claude Desktop, your terminal emulator)\n4. Ensure the toggle is enabled\n\n### Screen Recording\n\nRequired for screenshots.\n\n1. Open **System Settings** > **Privacy & Security** > **Screen Recording**\n2. Click the **+** button\n3. Add your MCP client application\n4. Ensure the toggle is enabled\n5. Restart the application if prompted\n\n### Verify permissions\n\nAfter granting both permissions and configuring your MCP client (see next section), use the `check_permissions` tool to confirm everything is working:\n\n```\n> check_permissions\n✓ Accessibility: granted\n✓ Screen Recording: granted\n```\n\n## MCP Client Configuration\n\n\nClaude Code
\n\n```bash\nclaude mcp add mac-use-mcp -- npx mac-use-mcp\n```\n\n \n\n\nClaude Desktop
\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"mac-use-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"mac-use-mcp\"]\n }\n }\n}\n```\n\n \n\n\nOpenAI Codex
\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.mac-use]\ncommand = \"npx\"\nargs = [\"-y\", \"mac-use-mcp\"]\n```\n\nOr via CLI:\n\n```bash\ncodex mcp add mac-use -- npx -y mac-use-mcp\n```\n\n \n\n\nGoogle Antigravity
\n\nAdd to `~/.gemini/antigravity/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"mac-use-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"mac-use-mcp\"]\n }\n }\n}\n```\n\n \n\n\nGemini CLI
\n\nAdd to `~/.gemini/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"mac-use-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"mac-use-mcp\"]\n }\n }\n}\n```\n\n \n\n\nVS Code / Copilot
\n\nAdd to `.vscode/mcp.json` in your workspace (or open the Command Palette and run **MCP: Open User Configuration** for global setup):\n\n```json\n{\n \"servers\": {\n \"mac-use-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"mac-use-mcp\"]\n }\n }\n}\n```\n\n \n\n\nCursor
\n\nAdd to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-level):\n\n```json\n{\n \"mcpServers\": {\n \"mac-use-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"mac-use-mcp\"]\n }\n }\n}\n```\n\n \n\n\nWindsurf
\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"mac-use-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"mac-use-mcp\"]\n }\n }\n}\n```\n\n \n\n\nCline
\n\nOpen Cline's MCP settings (in the Cline extension panel, click the MCP servers icon), then add:\n\n```json\n{\n \"mcpServers\": {\n \"mac-use-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"mac-use-mcp\"]\n }\n }\n}\n```\n\n \n\n\nKiro
\n\nAdd to `~/.aws/amazonq/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"mac-use-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"mac-use-mcp\"]\n }\n }\n}\n```\n\n \n\n## Tools\n\nThis Node.js MCP server exposes 18 tools for mouse, keyboard, and screen control to any MCP-compatible client.\n\n### Screen\n\n| Tool | Description |\n| --- | --- |\n| `screenshot` | Capture the screen, a region, or a window by title (PNG or JPEG) |\n| `get_screen_info` | Get display count, resolution, origin, and scale factor for each display |\n| `get_cursor_position` | Get current cursor coordinates |\n\n### Input\n\n| Tool | Description |\n| --- | --- |\n| `click` | Click at screen coordinates with button, click count, and modifier options |\n| `move_mouse` | Move the cursor to a position |\n| `scroll` | Scroll up, down, left, or right at a position |\n| `drag` | Drag from one point to another over a configurable duration |\n| `type_text` | Type text at the cursor position (supports Unicode, CJK, and emoji) |\n| `press_key` | Press a key or key combination (e.g., `\"cmd+c\"`, `\"Return\"`) |\n\n### Window & App\n\n| Tool | Description |\n| --- | --- |\n| `list_windows` | List all visible windows with positions and sizes |\n| `focus_window` | Activate an app and bring a specific window to the front |\n| `open_application` | Launch an application by name |\n| `click_menu` | Click a menu bar item by path (e.g., \"File > Save As...\") |\n\nApp names support fuzzy matching — `\"chrome\"` resolves to `\"Google Chrome\"`, `\"code\"` to `\"Code\"`, etc.\n\n### Accessibility\n\n| Tool | Description |\n| --- | --- |\n| `get_ui_elements` | Query UI elements via Accessibility API — find buttons, text fields, and other controls by role or title |\n\n### Clipboard\n\n| Tool | Description |\n| --- | --- |\n| `clipboard_read` | Read the current system clipboard as plain text |\n| `clipboard_write` | Write text to the system clipboard |\n\n### Utility\n\n| Tool | Description |\n| --- | --- |\n| `wait` | Pause for a specified duration (in milliseconds, 0–10 000, default 500) |\n| `check_permissions` | Verify Accessibility and Screen Recording access |\n\n## Examples\n\nCommon workflow patterns using mac-use-mcp tools:\n\n### Screenshot a specific window\n\n```\n1. focus_window({ app: \"Safari\" })\n2. screenshot({ mode: \"window\", window_title: \"Safari\" })\n```\n\n### Click a button in a dialog\n\n```\n1. get_ui_elements({ app: \"Finder\", role: \"AXButton\" })\n → finds \"OK\" button at position (500, 300)\n2. click({ x: 500, y: 300 })\n```\n\n### Automate a menu action\n\n```\n1. open_application({ name: \"TextEdit\" })\n2. click_menu({ app: \"TextEdit\", path: \"Format > Make Plain Text\" })\n```\n\n### Copy text between apps\n\n```\n1. focus_window({ app: \"Safari\" })\n2. press_key({ key: \"cmd+a\" }) # select all\n3. press_key({ key: \"cmd+c\" }) # copy\n4. focus_window({ app: \"Notes\" })\n5. press_key({ key: \"cmd+v\" }) # paste\n```\n\n## How It Works\n\n- **Swift binary** handles mouse input (CGEvent), screen capture (CGWindowListCreateImage), window enumeration (CGWindowListCopyWindowInfo), and UI element queries (Accessibility API)\n- **AppleScript** handles keyboard input (System Events `key code`), window focus, and menu clicks\n- **Node.js MCP server** orchestrates everything over stdio, translating MCP tool calls into system operations\n- **No native Node.js addons** — the Swift binary is pre-compiled and ships with the npm package\n- **Serial execution queue** prevents race conditions between system operations\n\n## Known Limitations\n\n- **Screen Recording prompt on Sequoia**: macOS 15 shows a monthly system prompt asking to reconfirm Screen Recording access. This is an OS-level behavior and cannot be suppressed.\n- **Secure input fields**: Password fields and other secure text inputs block synthetic keyboard events. This is a macOS security feature.\n- **Keyboard input on macOS 26+**: CGEvent keyboard synthesis is silently blocked. Keyboard input uses AppleScript (`System Events key code`) as a workaround, which may behave differently in some edge cases.\n- **System dialogs**: Some system-level dialogs (e.g., FileVault unlock, Login Window) cannot be interacted with programmatically due to macOS security restrictions.\n- **Headless / CI**: Requires a graphical session. Headless macOS environments (e.g., standard GitHub Actions runners) are not supported.\n\n## Troubleshooting\n\n\nPermission prompts keep appearing
\n\nGrant Accessibility and Screen Recording permissions to your terminal app in System Settings > Privacy & Security. A restart of the terminal may be required.\n\n \n\n\nmacOS Sequoia permission dialogs
\n\nmacOS 15 (Sequoia) introduced stricter permission prompts. Allow the prompts when they appear. The `check_permissions` tool can verify your current permission status.\n\n \n\n\nSecure input fields
\n\nSome password fields and secure text inputs block programmatic key events. This is a macOS security feature. Use `clipboard_write` + `press_key(\"cmd+v\")` as a workaround.\n\n \n\n\nScreen recording shows black screenshots
\n\nEnsure Screen Recording permission is granted to your terminal app (not just Accessibility). Restart the terminal after granting.\n\n \n\n## Related Projects\n\n- [Playwright MCP](https://github.com/microsoft/playwright-mcp) — Browser automation via accessibility tree. Complements mac-use-mcp for web-only tasks.\n- [Peekaboo](https://github.com/steipete/Peekaboo) — macOS screen automation with ScreenCaptureKit. Requires macOS 15+ and a Swift build.\n- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) — Curated list of MCP servers across the ecosystem.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n[Changelog](CHANGELOG.md)\n\n## Security\n\nTo report a vulnerability, see [SECURITY.md](SECURITY.md).\n\n## Support\n\n- Found a bug? [Open an issue](https://github.com/antbotlab/mac-use-mcp/issues)\n- Have a feature idea? [Open an issue](https://github.com/antbotlab/mac-use-mcp/issues)\n- Like the project? Give it a star — it helps others discover mac-use-mcp.\n\n## License\n\n[MIT](./LICENSE) © 2026 antbotlab\n\n---\n\nmacOS is a trademark of Apple Inc., registered in the U.S. and other countries and regions.\n",
"bytes": 12678,
"sha": "92253af2d808f3f2b62ef238b9890d2eb056f5eb060a52e6b23b045d90fcec9f",
"repo_slug": "antbotlab/mac-use-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_antbotlab_mac_use_mcp_e74f8e28/readme"
}