home / mcp / macos gui control mcp server

macOS GUI Control MCP Server

Provides full macOS GUI control via MCP, including mouse, keyboard, screen capture, and window management actions.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "akira-papa-macos-gui-control-mcp": {
      "command": "node",
      "args": [
        "/path/to/macOS-GUI-Control-MCP/server/index.js"
      ],
      "env": {
        "TIMEOUT": "30000",
        "LOG_OPERATIONS": "true"
      }
    }
  }
}

You can remotely control macOS input devices and screen capture using this MCP server. It lets you perform mouse and keyboard actions, capture screenshots, manage windows, run AppleScript or shell commands, and more, all through a consistent MCP interface. This is especially useful for automating GUI tasks or building assistive workflows on macOS.

How to use

You interact with the MCP server through an MCP client. Start the server as described in the installation steps, then reference the available actions by name from your client. Typical usage includes clicking at coordinates, typing text, taking screenshots, listing windows, activating apps, resizing windows, and running auxiliary commands. Commands are expressed using the tool names shown in the action list, and you can combine multiple actions in sequences to automate complex GUI tasks.

How to install

Prerequisites you need before installing the MCP server are Node.js and a working macOS environment with the necessary permissions.

Install the build toolchain and MCP packager, then package the MCP server for distribution.

Install dependencies and package the MCP server.

Additional setup and usage notes

This server requires the following environment variables to control timeouts and logging behavior. You can set these as shown in the MCP configuration example.

Available tools

mouse_click

Click at specified coordinates on the screen.

mouse_double_click

Perform a double-click at the given coordinates.

mouse_right_click

Right-click at the specified coordinates.

mouse_move

Move the cursor to the specified coordinates.

mouse_drag

Drag the cursor from one coordinate to another.

mouse_scroll

Scroll the mouse wheel in up/down/left/right directions.

mouse_get_position

Retrieve the current cursor position.

keyboard_type

Type a string of text into the focused input.

keyboard_press

Press a single key, with optional modifier keys.

keyboard_shortcut

Execute a common keyboard shortcut like copy/paste/save.

screen_capture

Take a full-screen or region-based screenshot.

screen_get_size

Get the current screen resolution.

screen_get_color

Get the color value of a pixel at a coordinate.

window_list

List currently open windows.

window_focus

Activate a specific application window.

window_move

Move a window to new coordinates.

window_resize

Resize a window to specified dimensions.

run_applescript

Execute an AppleScript script.

run_shell

Run a shell command and return its output.