mac-use-mcp

[!WARNING] 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.

Zero-native-dependency macOS desktop automation via MCP.

Give AI agents eyes and hands on macOS — click, type, screenshot, and inspect any application.

Use Cases

• Automated UI testing — click buttons, verify element states with get_ui_elements, validate screen content via screenshot
• Desktop workflow automation — launch apps with open_application, fill forms with type_text, navigate menus via click_menu
• Screenshot-based monitoring — capture screen regions periodically with screenshot for visual diffing or alerting
• Accessibility inspection — query UI element trees with get_ui_elements for QA and compliance checks
• AI agent computer use — give LLMs eyes and hands on macOS via screenshot, click, type_text, and more

Why mac-use-mcp?

• Just works — npx mac-use-mcp and grant two macOS permissions. No node-gyp, no Xcode tools, no build step.
• 18 tools, one server — screenshots, clicks, keystrokes, window management, accessibility inspection, and clipboard.
• macOS 13+ on Intel and Apple Silicon — no native addons, no architecture headaches.

Install

Requirements: macOS 13+ and Node.js 22+. The server communicates over stdio transport.

This package only works on macOS. It will refuse to install on other operating systems.

No build steps. No native dependencies. Just run:

npx mac-use-mcp

npx will prompt to install the package on first run. Use npx -y mac-use-mcp to skip the confirmation.

[!TIP] 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:

Model	Provider
Gemini 3 Flash	Google
Claude Sonnet 4.6	Anthropic
GPT-5 mini	OpenAI
MiniMax-M2.5	MiniMax
Kimi K2.5	Moonshot AI
Qwen3.5	Alibaba
GLM-4.7	Zhipu AI

Permission Setup

mac-use-mcp requires two macOS permissions to function. Grant them once and you're set.

Accessibility

Required for mouse and keyboard control.

1. Open System Settings > Privacy & Security > Accessibility
2. Click the + button
3. Add your MCP client application (e.g., Claude Desktop, your terminal emulator)
4. Ensure the toggle is enabled

Screen Recording

Required for screenshots.

1. Open System Settings > Privacy & Security > Screen Recording
2. Click the + button
3. Add your MCP client application
4. Ensure the toggle is enabled
5. Restart the application if prompted

Verify permissions

After granting both permissions and configuring your MCP client (see next section), use the check_permissions tool to confirm everything is working:

> check_permissions
✓ Accessibility: granted
✓ Screen Recording: granted

MCP Client Configuration

claude mcp add mac-use-mcp -- npx mac-use-mcp

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

[mcp_servers.mac-use]
command = "npx"
args = ["-y", "mac-use-mcp"]

codex mcp add mac-use -- npx -y mac-use-mcp

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "servers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

Tools

This Node.js MCP server exposes 18 tools for mouse, keyboard, and screen control to any MCP-compatible client.

Screen

Input

Window & App

App names support fuzzy matching — "chrome" resolves to "Google Chrome", "code" to "Code", etc.

Accessibility

Clipboard

Utility

Examples

Common workflow patterns using mac-use-mcp tools:

Screenshot a specific window

1. focus_window({ app: "Safari" })
2. screenshot({ mode: "window", window_title: "Safari" })

Click a button in a dialog

1. get_ui_elements({ app: "Finder", role: "AXButton" })
   → finds "OK" button at position (500, 300)
2. click({ x: 500, y: 300 })

Automate a menu action

1. open_application({ name: "TextEdit" })
2. click_menu({ app: "TextEdit", path: "Format > Make Plain Text" })

Copy text between apps

1. focus_window({ app: "Safari" })
2. press_key({ key: "cmd+a" })       # select all
3. press_key({ key: "cmd+c" })       # copy
4. focus_window({ app: "Notes" })
5. press_key({ key: "cmd+v" })       # paste

How It Works

• Swift binary handles mouse input (CGEvent), screen capture (CGWindowListCreateImage), window enumeration (CGWindowListCopyWindowInfo), and UI element queries (Accessibility API)
• AppleScript handles keyboard input (System Events key code), window focus, and menu clicks
• Node.js MCP server orchestrates everything over stdio, translating MCP tool calls into system operations
• No native Node.js addons — the Swift binary is pre-compiled and ships with the npm package
• Serial execution queue prevents race conditions between system operations

Known Limitations