mac-mcp-server

You can automate macOS with the mac-mcp-server, a macOS MCP server that uses AppleScript and JXA to expose 44 practical tools for system information, window and app management, input simulation, UI interaction, and more. It communicates over stdio for seamless integration with Claude Code and similar AI assistants, letting you control your Mac through high-level tool calls.

How to use

To use this MCP server, you run it as a local stdio server and connect your MCP client (such as Claude Code) to it. You will then call the available tools by name to retrieve data, control applications, manipulate windows, simulate input, and perform automation tasks across macOS. Focus on practical tasks like listing running apps, launching or quitting programs, moving windows, typing text, taking screenshots, and interacting with UI elements. Each tool returns structured results that you can feed into your automation flows.

How to install

Prerequisites you need before installing: macOS 10.15 (Catalina) or later and Node.js 20.11.0 or later.

npm install -g mac-mcp-server

Configure the MCP client (Claude Code) to connect to the server by adding the following MCP configuration. This enables Claude Code to start the mac-mcp-server via npx and pass commands to it.

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

Restart your MCP client (Claude Code) after saving the configuration to load and start the MCP server.

Grant macOS permissions when prompted to enable accessibility, automation, and screen recording as part of the first-use flow described in the Permissions section.

Additional sections

This server exposes a comprehensive set of tools you can call from your MCP client. Each tool is designed for a specific automation task on macOS, ranging from system information and audio control to Finder integration, window management, and UI element interaction.

Permissions and security

macOS requires explicit permissions for automation. You will be prompted to enable the following when using relevant tools for the first time: Accessibility (control of the keyboard and mouse, UI element interaction, and window management), Automation (control of other apps), and Screen Recording (for taking screenshots). Follow the quick-access instructions to grant these permissions, and restart your terminal or client after enabling each permission.

Important security practices: all automation runs via AppleScript/JXA, inputs are sanitized, no data is persisted, and access is scoped to the intended tools. Ensure you only enable permissions for trusted clients and scripts.

Usage examples

System information: get_system_info and get_battery_status help you learn about the machine and its state.

Application control: list_running_apps, launch_app, and quit_app let you manage software lifecycle from your automation flow.

Window operations: list_windows, focus_window, move_window, resize_window, and minimize_window give you precise control over app windows.

Input and navigation: type_text, press_key, key_combination, click, and drag allow you to simulate user actions.

Screenshots: take_screenshot captures visuals with automatic resizing and compression optimizations for API use.

UI interactions: get_ui_elements, click_ui_element, get_ui_element_value, set_ui_element_value, and focus_ui_element enable automated UI manipulation.

Notes on configuration and troubleshooting

The MCP server uses stdio for communication. Ensure your client is configured to connect via the standard input/output channels, and that the command to start the server is correctly exposed in your client configuration.

If you encounter permission issues, verify that the terminal or client app has Accessibility, Automation, and Screen Recording permissions as described in the macOS Permissions section. A full restart of the terminal or client often resolves lingering permission prompts.

Troubleshooting permissions

If permissions appear but the tools still fail, completely quit and reopen the terminal or client app after granting permissions. If an app does not appear in the permission lists, trigger the permission dialog by performing the operation once.

If issues persist after granting permissions, restart macOS as a last resort to clear any lingering authorization state.

Available tools

get_system_info

Retrieves macOS version, hardware model, processor, and memory.

get_battery_status

Gets battery percentage and charging status (MacBooks).

get_display_info

Lists connected displays with resolution information.

get_volume

Gets current system volume (0-100).

set_volume

Sets system volume to a specified percentage.

get_mute_status

Checks if the system audio is muted.

set_mute

Mutes or unmutes system audio.

get_clipboard

Reads current clipboard content (text, image, or files).

set_clipboard

Sets clipboard to specified text.

send_notification

Displays a macOS notification with optional subtitle and sound.

list_running_apps

Lists all running GUI applications with bundle IDs and PIDs.

launch_app

Launches an application by name.

quit_app

Gracefully quits an application.

activate_app

Brings an application to the foreground.

reveal_in_finder

Opens Finder and selects the specified file or folder.

get_selected_files

Gets paths of currently selected files in Finder.

get_finder_window_path

Gets the path of the frontmost Finder window.

list_windows

Lists all visible windows with position and size.

focus_window

Brings a specific window to the front.

move_window

Moves a window to specified coordinates.

resize_window

Resizes a window to specified dimensions.

minimize_window

Minimizes a window to the Dock.

click

Performs a mouse click with configurable button and coordinates.

double_click

Performs a double-click at a location.

move_mouse

Moves the cursor to a specified position without clicking.

drag

Performs a drag operation from start to end coordinates.

type_text

Types text at the current cursor position.

press_key

Presses a key by name (e.g., Enter, Tab, Escape, F1-F12).

key_combination

Presses a key combination (e.g., Cmd+C).

scroll

Scrolls in a specified direction (up, down, left, right).

scroll_to_element

Scrolls until a UI element becomes visible.

take_screenshot

Captures screen, display, window, or region as PNG/JPEG with auto-processing.

get_ui_elements

Retrieves the UI element tree for an application.

click_ui_element

Clicks a UI element by path.

get_ui_element_value

Gets the value of a UI element.

set_ui_element_value

Sets the value of an editable UI element.

focus_ui_element

Sets keyboard focus to a UI element.

list_menu_items

Gets the menu hierarchy for an application.

click_menu_item

Clicks a menu item by path.

get_menu_item_state

Gets enabled/checked state of a menu item.

list_status_bar_items

Lists visible status bar items.

click_status_bar_item

Clicks a status bar item to open its menu.

click_status_bar_menu_item

Clicks a menu item within a status bar menu.

get_menu_bar_structure

Gets complete menu bar hierarchy for a process.