MCP server for macOS

Your Mac, one MCP call away.

mac-orchestrator gives AI agents real mouse, keyboard, and screen access, plus a full terminal, through a single self-hosted MCP server.

Install View on GitHub

agent session

One server. Both hands.

Most Mac automation tools do one thing. Either they drive the interface, clicking and typing like a human would, or they open a shell and run commands. mac-orchestrator does both from the same server, so an agent can read what's on screen, click through a dialog, then drop into the terminal to finish the job with a script.

UI AUTOMATION

Mouse, keyboard, app focus, and screen reading via macOS's Accessibility API and OCR, for the parts of a job that only exist in a window.

TERMINAL AUTOMATION

Direct shell and filesystem access, for the parts of a job that are faster as a command than a click.

Twenty tools, one endpoint.

Every tool below is exposed over the same MCP connection. No per-tool plugins, no separate servers to run.

Keyboard & mouse

press_keystroke
type_text
mouse_action
scroll

Macros

execute_macro

App control

focus_app
get_available_apps

Screen OCR + layout

get_screen_text
get_screen_layout
get_screen_size

Terminal

run_terminal_command

Files

find_file, read_file, write_file
list_directory, smart_search, vector_search

Utility

clipboard, play_sound_for_user_prompt, send_file_to_telegram

How it connects.

An agent talks to mac-orchestrator over plain HTTP. The server translates that into real macOS system calls.

AI agent

Claude, or any MCP client

HTTP / MCP

localhost:8000/mcp

mac-orchestrator

FastMCP server

macOS system APIs

pyobjc, AppleScript, EasyOCR, shell

Using a cloud-based agent instead of a local one. An optional ngrok tunnel exposes the same endpoint over HTTPS, so nothing changes on the agent's side.

Get it running.

No package manager install yet. Clone the repository and run it with uv.

            $git clone https://github.com/Jay-2212/mac-orchestrator.git
            $cd mac-orchestrator
            $uv sync
            $uv run python automac_mcp.py
          

macOS will ask for Accessibility and Screen Recording permissions the first time a tool runs. Grant both, then point any MCP client at the URL the server prints on startup. A Telegram bot token and an ngrok authtoken are optional, for remote alerts and remote access.

Read before you run it.

This gives an agent the same access you have.

Anything the tools can do, a connected agent can do: click any button, read anything on screen, run any shell command. There's no sandboxing between the agent and your machine.

Only run it on a machine you fully control, and never expose the port to the internet without putting real authentication in front of it first.