mac-use-mcp

Check whether macOS Accessibility and Screen Recording permissions are granted. Returns status for each permission and instructions for any that are missing.

Pause execution for a specified duration. Useful for waiting between UI operations.

Retrieve display configuration: number of displays, per-display resolution, origin, and scale factor.

Get the current mouse cursor position in screen coordinates.

Capture a screenshot of the macOS screen. Supports full screen, a rectangular region, or a specific window by title. Returns a base64-encoded image with dimension metadata. Do not narrate visual observations or coordinate calculations. Brief task progress updates are acceptable.

Click at the specified screen coordinates. Supports left/right/middle button, single/double/triple click, and modifier keys. Do not narrate visual observations or coordinate calculations. Brief task progress updates are acceptable.

Move the mouse cursor to the specified screen coordinates without clicking. Do not narrate visual observations or coordinate calculations. Brief task progress updates are acceptable.

Scroll at the specified screen coordinates in the given direction. Do not narrate visual observations or coordinate calculations. Brief task progress updates are acceptable.

Drag from one screen coordinate to another over a specified duration.

Best practices for window dragging:

• Always call focus_window on the target app immediately BEFORE dragging to ensure the window is frontmost. Without this, the drag may land on a different overlapping window and silently fail.

• Start coordinates must land on the window's title bar — use the far-right edge of the title bar to avoid traffic-light buttons and any center toolbar icons.

• Use a duration of 600–1000 ms. Too short and macOS may not recognize it as a drag gesture.

Do not narrate visual observations or coordinate calculations. Brief task progress updates are acceptable.

Type text at the current cursor position using clipboard paste. Supports full Unicode including CJK characters and emoji. Temporarily replaces clipboard contents. Non-text clipboard content (images, files) will be lost permanently. If secure input is active (e.g. password fields), returns a note suggesting clipboard_write + press_key("cmd+v") as an alternative.

Simulate a key press with optional modifiers. Accepts a key combo string like "cmd+c", "ctrl+shift+F5", or "Return". Modifiers: cmd, ctrl, shift, opt/alt.

List visible windows with their app name, title, ID, position, size, and minimized state. Optionally filter by application name. App name supports fuzzy matching (case-insensitive, partial names like 'chrome' for 'Google Chrome').

Activate an application and optionally raise a specific window by title. App name supports fuzzy matching.

Launch an application by name or bundle identifier. App name supports fuzzy matching (e.g. 'chrome' → 'Google Chrome').

Read the current contents of the macOS clipboard as plain text.

Write text to the macOS clipboard.

Click a menu bar item in an application. Specify the menu path as "Menu > Submenu > Item" (e.g., "File > Save As...", "View > Sort By > Name").

Query visible UI elements of an application via macOS Accessibility API. Returns element roles, titles, positions (screen coordinates), sizes, and states. May return text content from visible UI elements including sensitive data (passwords in non-secure fields, messages, etc.). Positions are in logical screen coordinates — pass directly to click tool. Coverage varies: native apps expose rich trees; Electron/web apps may expose partial trees; games/custom UIs may expose nothing. Requires Accessibility permission.