Mac Use Mcp

io.github.antbotlabPublished by GitHub account antbotlabv1.1.1Updated Oct 24, 2026

Zero-dependency macOS desktop automation for AI agents. 18 tools via MCP. macOS 13+.

VerifiedSTDIODesktop onlyBrowser AutomationDeveloper Tools

Overview

AI-generated overview

A local macOS MCP server that gives an AI assistant control of the mouse, keyboard, screen, windows, apps and clipboard.

What you can do
Capture screenshots of the screen, a region or a window, and read display and cursor information. Click, move, scroll, drag, type text and press key combinations. List and focus windows, launch applications and click menu bar items. Query UI elements through the Accessibility API. Read and write the system clipboard, wait, and check permission status.
When to use it
Useful for automated UI testing, desktop workflow automation, screenshot-based monitoring, accessibility inspection, or giving an agent hands-on control of macOS applications. Only relevant if you work on a Mac with a graphical session.
Requirements
macOS 13 or later on Intel or Apple Silicon, Node.js 22 or later, and a graphical (non-headless) session. Runs locally over stdio, for example via npx. Requires macOS Accessibility and Screen Recording permissions granted to the MCP client or terminal app.
Before you install
The server has full control over mouse, keyboard and screen, so an agent can click, type, launch apps and change or delete data; the README recommends a sandboxed environment. Clipboard contents can be read and written. Secure password fields block synthetic input, and the README suggests pasting via the clipboard as a workaround. Headless and CI environments are not supported.

Installation

In SourceWeft

  1. Open Mac Use Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[ant-09-banner-night-03]

mac-use-mcp

[demo]

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

[CI] [npm version] [npm downloads] [license] [TypeScript] [macOS 13+] [Node 22+]

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:

bash
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:

ModelProvider
Gemini 3 FlashGoogle
Claude Sonnet 4.6Anthropic
GPT-5 miniOpenAI
MiniMax-M2.5MiniMax
Kimi K2.5Moonshot AI
Qwen3.5Alibaba
GLM-4.7Zhipu 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 Code
bash
claude mcp add mac-use-mcp -- npx mac-use-mcp
Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Add to ~/.codex/config.toml:

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

Or via CLI:

bash
codex mcp add mac-use -- npx -y mac-use-mcp
Google Antigravity

Add to ~/.gemini/antigravity/mcp_config.json:

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

Add to ~/.gemini/settings.json:

json
{  "mcpServers": {    "mac-use-mcp": {      "command": "npx",      "args": ["mac-use-mcp"]    }  }}
VS Code / Copilot

Add to .vscode/mcp.json in your workspace (or open the Command Palette and run MCP: Open User Configuration for global setup):

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

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-level):

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

Add to ~/.codeium/windsurf/mcp_config.json:

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

Open Cline's MCP settings (in the Cline extension panel, click the MCP servers icon), then add:

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

Add to ~/.aws/amazonq/mcp.json:

json
{  "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

ToolDescription
screenshotCapture the screen, a region, or a window by title (PNG or JPEG)
get_screen_infoGet display count, resolution, origin, and scale factor for each display
get_cursor_positionGet current cursor coordinates

Input

ToolDescription
clickClick at screen coordinates with button, click count, and modifier options
move_mouseMove the cursor to a position
scrollScroll up, down, left, or right at a position
dragDrag from one point to another over a configurable duration
type_textType text at the cursor position (supports Unicode, CJK, and emoji)
press_keyPress a key or key combination (e.g., "cmd+c", "Return")

Window & App

ToolDescription
list_windowsList all visible windows with positions and sizes
focus_windowActivate an app and bring a specific window to the front
open_applicationLaunch an application by name
click_menuClick a menu bar item by path (e.g., "File > Save As...")

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

Accessibility

ToolDescription
get_ui_elementsQuery UI elements via Accessibility API — find buttons, text fields, and other controls by role or title

Clipboard

ToolDescription
clipboard_readRead the current system clipboard as plain text
clipboard_writeWrite text to the system clipboard

Utility

ToolDescription
waitPause for a specified duration (in milliseconds, 0–10 000, default 500)
check_permissionsVerify Accessibility and Screen Recording access

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 all3. press_key({ key: "cmd+c" })       # copy4. 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

  • 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.
  • Secure input fields: Password fields and other secure text inputs block synthetic keyboard events. This is a macOS security feature.
  • 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.
  • System dialogs: Some system-level dialogs (e.g., FileVault unlock, Login Window) cannot be interacted with programmatically due to macOS security restrictions.
  • Headless / CI: Requires a graphical session. Headless macOS environments (e.g., standard GitHub Actions runners) are not supported.

Troubleshooting

Permission prompts keep appearing

Grant Accessibility and Screen Recording permissions to your terminal app in System Settings > Privacy & Security. A restart of the terminal may be required.

macOS Sequoia permission dialogs

macOS 15 (Sequoia) introduced stricter permission prompts. Allow the prompts when they appear. The check_permissions tool can verify your current permission status.

Secure input fields

Some 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.

Screen recording shows black screenshots

Ensure Screen Recording permission is granted to your terminal app (not just Accessibility). Restart the terminal after granting.

Related Projects

  • Playwright MCP — Browser automation via accessibility tree. Complements mac-use-mcp for web-only tasks.
  • Peekaboo — macOS screen automation with ScreenCaptureKit. Requires macOS 15+ and a Swift build.
  • awesome-mcp-servers — Curated list of MCP servers across the ecosystem.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Changelog

Security

To report a vulnerability, see SECURITY.md.

Support

  • Found a bug? Open an issue
  • Have a feature idea? Open an issue
  • Like the project? Give it a star — it helps others discover mac-use-mcp.

License

MIT © 2026 antbotlab

macOS is a trademark of Apple Inc., registered in the U.S. and other countries and regions.

Source: README.md at commit f19bbd9

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts