macos_ui_automation

This MCP server lets Claude interact with native macOS applications just like Playwright does for web browsers. You can automate UI tasks, verify accessibility, and test Mac apps by expressing your needs in natural language and letting Claude drive the macOS UI through a dedicated MCP endpoint.

How to use

You use this server by connecting a client (such as Claude) that supports MCP to the local MCP endpoint. The server exposes high-level actions like locating UI elements, clicking, typing, and validating app state. Describe what you want to achieve in natural language, for example to find a button, fill a form, or take a screenshot, and the MCP server will translate that into UI actions against the target macOS application.

How to install

Prerequisites: ensure you have a macOS environment and the tooling required to run the MCP server.

1. Clone the MCP project and prepare the environment.

git clone https://github.com/mb-dev/macos-ui-automation-mcp.git
cd macos-ui-automation-mcp
uv sync

2. Set up Accessibility permissions for the parent application that will execute the MCP server. Grant accessibility to the terminal, VS Code, Claude Code, or whichever parent app you use.

3. Configure Claude Code to register the MCP server using the provided configuration snippet.

{
  "mcpServers": {
    "macos-ui-automation": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/macos-ui-automation-mcp",
        "run",
        "macos-ui-automation-mcp"
      ]
    }
  }
}

4. Start the MCP server to begin automating your macOS UI.

uv run macos-ui-automation-mcp

Additional configuration and usage notes

Accessibility permissions must be granted to the parent application that runs the MCP server. If you are using Terminal, add Terminal to Privacy & Security → Accessibility. If you are using VS Code or Claude Code, add the respective application there.

There is no built-in screenshot capture in the MCP server itself; you can integrate screenshot functionality into your Mac app and trigger it via an accessibility-identified control when needed.

For contributors and advanced users, you can run tests and perform quality checks with the following commands.

Practical examples

Ask Claude to perform actions like: Find all buttons in the Calculator app, Click the submit button in your app, or Test the login flow by filling in credentials and submitting.

Troubleshooting and tips

If actions don’t behave as expected, verify that accessibility permissions are correctly granted for the parent application and that the target app is running. Use shallow element searches for quick overviews and deeper searches for thorough checks, understanding deeper searches may take longer.

Available tools

find_elements

Find UI elements using JSONPath expressions to identify controls like buttons, text fields, and labels across apps.

find_elements_in_app

Search within a specific running application to locate elements by role or identifier.

click_by_accessibility_id

Click UI controls using their accessibility identifiers to simulate user actions.

click_at_position

Click on screen coordinates to interact with precise UI locations.

type_text_to_element_by_selector

Type text into UI elements identified by selectors or attributes.

get_app_overview

Get a high-level view of currently running applications.

list_running_applications

List all applications currently running on the system.

check_accessibility_permissions

Verify that accessibility permissions are properly configured for the automation workflow.