macOS Control

This MCP server lets you automate and control your macOS desktop through a unified Model Context Protocol interface. You can move and click the mouse, type on the keyboard, take and analyze screenshots, locate elements on screen, and insert purposeful pauses. It’s designed to be used with an MCP client to perform complex desktop automation safely and repeatedly.

How to use

You connect to the macOS Control MCP Server with an MCP client to send actions. You can combine mouse moves, clicks, and drags with keyboard input and screen operations in a sequence that automates tasks on macOS. The server supports safety features like a failsafe and configurable pauses between actions to prevent rapid, unintended automation.

How to install

Prerequisites you need before installing the MCP server are listed here. Make sure you have macOS, Python 3.10 or later, and a supported MCP runtime/manager available on your system.

Step by step installation and setup you can follow locally:

# 1) Open a terminal and navigate to your project directory
cd ~/macos-control-mcp

# 2) Install dependencies using the MCP runtime manager
uv sync

# 3) Grant necessary accessibility and screen recording permissions in macOS:
#   Accessibility: System Settings → Privacy & Security → Accessibility
#   Screen Recording: System Settings → Privacy & Security → Screen Recording
#   Add your terminal application to both permissions

# 4) Run the MCP server (from project directory)
uv run macos-control-mcp
```} ,{

Configuration and usage notes

Configuration for running the MCP server locally uses uv to load the server from a specified directory. The typical setup provided for development includes pointing the MCP runtime to the server folder and starting the runtime with the server name.

{
  "mcpServers": {
    "macos-control": {
      "command": "uv",
      "args": [
        "--directory",
        "<path_to_folder>/macos-control-mcp",
        "run",
        "macos-control-mcp"
      ]
    }
  }
}
````}]} ,{

Safety and troubleshooting

Safety features are included to prevent unintended automation. A failsafe is enabled by default and aborts actions if you move the mouse to any screen corner. You can disable it per your needs, but use caution. A short, configurable pause is inserted between actions to help you verify each step in a run.

If you encounter permission or runtime issues, ensure your terminal app has Accessibility and Screen Recording permissions, and verify that the MCP server command and directory path you provided match your local setup.

Troubleshooting tips

Permission denied: Confirm you granted Accessibility and Screen Recording permissions to the terminal application. If image searches fail, try reducing the image recognition confidence threshold. If the server does not respond, review the running logs and ensure the path to the MCP folder is correct, then restart the server.

Examples of what you can do

Mouse control: move the mouse, click, double-click, right-click, scroll, and drag to precise coordinates.

Keyboard control: type text, press individual keys, run hotkey combinations, and hold/release keys.

Screen operations: take screenshots, get screen size, locate images on screen, and read pixel colors.

Notes

This MCP server is designed for macOS desktop automation and is intended to be used with MCP clients to drive desktop tasks programmatically.

Available tools

move_mouse

Move the cursor to specified x,y coordinates over an optional duration.

click_mouse

Click at a given coordinate with a chosen button and number of clicks.

double_click

Perform a double-click at the specified position.

right_click

Right-click at the given coordinate.

scroll_mouse

Scroll the mouse wheel by a number of clicks at a position.

drag_mouse

Drag the cursor from one coordinate to another.

get_mouse_position

Retrieve the current cursor position.

type_text

Type a string of text with an optional interval between characters.

press_key

Press a single key a number of times with an interval.

hotkey

Press a combination of keys together as a hotkey.

key_down

Hold down a specific key.

key_up

Release a held key.

get_screen_size

Return the current screen resolution.

take_screenshot

Capture a screenshot, either full screen or a region.

locate_on_screen

Find an image on the screen with an optional confidence parameter.

get_pixel_color

Get the RGB color at a specific screen coordinate.

sleep

Pause execution for a given number of seconds.

set_failsafe

Enable or disable the mouse-corner failsafe.

set_pause

Set the default pause duration between actions.