mctrl lets your agents type, click, read screens, fill forms, control browsers, and more.
Primitives
Everything an agent needs to see, interact with, and control a Mac.
Type text, press keys, and trigger hotkeys.
$ mctrl keyboard type "Hello world"$ mctrl keyboard hotkey cmd+cMove, click, scroll, and drag anywhere on screen.
$ mctrl mouse click 500 300$ mctrl mouse scroll -3Screen dimensions, screenshots, and active window info.
$ mctrl display screenshot -o shot.png$ mctrl display size --jsonRead and write the system clipboard.
$ mctrl clipboard copy "data"$ mctrl clipboard viewExtract text from the screen using the Vision framework.
$ mctrl screen ocr$ mctrl screen ocr --jsonList, focus, resize, move, and minimize windows.
$ mctrl window list --json$ mctrl window focus "Terminal"Inspect the accessibility tree and get focused elements.
$ mctrl a11y tree --app Finder$ mctrl a11y focused --jsonControl Chrome and Safari. Open URLs, run JS, read page source.
$ mctrl browser open "https://example.com"$ mctrl browser tabsSearch, read, write, and edit files on disk.
$ mctrl files search "TODO" --dir .$ mctrl files read config.jsonSend notifications, launch apps, and get the frontmost app.
$ mctrl os notify "Done!"$ mctrl os frontmost-app --jsonList and create calendar events via Apple Calendar.
$ mctrl calendar list --days 7$ mctrl calendar create "Meeting"Send and read iMessages.
$ mctrl sms send "+1234" "Hello"$ mctrl sms get --limit 5For Agents
Every command returns parseable text or JSON. Every flag has comprehensive help. Agents can discover and use capabilities without any extra setup.
$ mctrl display active-window --json
{ "app": "Chrome", "title": "GitHub", "x": 0, "y": 25 }
$ mctrl screen ocr --json
[{ "text": "Sign in", "confidence": 0.98, "x": 510, "y": 340 }]
$ mctrl mouse click 510 340
Clicked at (510, 340)
$ mctrl keyboard type "agent@example.com"
Typed 17 characters
$ mctrl keyboard press Tab
$ mctrl keyboard press ReturnGet Started
Clone, build, and link. Requires Node.js 18+ and macOS.
git clone https://github.com/enoreyes/mctrl.git
cd mctrl && npm install && npm run build
npm link
mctrl --help