macctl

Accessibility-first macOS desktop automation for Claude and other MCP clients.

macctl gives an MCP client first-class access to a Mac: it can see the screen, read the accessibility tree of any application to identify controls by role/title/identifier (not just pixels), drive the mouse and keyboard, manage windows, inspect processes and launchd services, work with files and the clipboard, and run shell commands — all gated behind explicit permission tiers, with a local audit log of every call. It is the macOS counterpart to winctl, Sitharaj's Windows equivalent.

Why macctl

• Accessibility-tree-first, not screenshot-and-click. ax_snapshot and ax_find let a client locate "the Save button" or "the text field named Subject" by role/title/identifier via AXUIElement, instead of guessing pixel coordinates from a screenshot and hoping the layout doesn't shift.
• Correct global-point coordinates. Every coordinate macctl reports or accepts is a global screen point in the CG coordinate space (top-left origin of the main display), with each display's backingScaleFactor reported alongside — no silent pixel/point confusion across Retina and external displays.
• Reliable, paced input. Keystrokes are synthesized layout-independently; text longer than ~200 characters is delivered via a clipboard paste (with the prior clipboard contents restored afterward) instead of hundreds of individually racy synthetic keypresses.
• Stable, opaque handles. windowHandle and elementHandle values are fingerprinted (pid + window/element identity) rather than raw pointers, so a handle from one call either still resolves correctly on the next call or fails cleanly — it never silently targets the wrong window.
• Honest, verified failures. Window moves are read back and the verified final frame is returned (apps clamp geometry); TCC failures come back as a structured PERMISSION_MISSING error naming the exact permission and the exact app to grant it to, not a generic timeout.
• Tiered permissions + audit log. Every tool belongs to one of five permission tiers. Tools in a disabled tier are never registered with the MCP client — it cannot see or attempt them, not just be told no. Every call is appended to a local, redacted JSONL audit log.

Requirements

• macOS 14 (Sonoma) or later recommended; built and tested on macOS 26.
• Apple Silicon or Intel — macctl ships a universal (arm64 + x86_64) helper binary, no compilation required on your machine.
• Node.js 20+.

Grant permissions

macctl's native tools (window management, input, accessibility, screen capture) need macOS permissions granted through System Settings → Privacy & Security, not through macctl itself. This is the single most common source of confusion, so read this before anything else:

The permission grant attaches to whichever app launches macctl — Claude Desktop, Terminal, iTerm2, VS Code, or whatever process ultimately spawns node dist/index.js — never to node or macctl themselves. If you grant Accessibility to the wrong app, or grant it and then keep running the old process, tools will keep failing with PERMISSION_MISSING.

Steps:

1. Run the doctor tool to find out exactly which app to grant, and get a direct System Settings link for each permission:

   npx @sitharaj88/macctl doctor

   This prints the responsible app (identified by walking the process tree up to the nearest .app bundle), the current status of Accessibility, Screen Recording, and Full Disk Access, and a x-apple.systempreferences: deep link for each one that isn't granted yet.

2. Open System Settings → Privacy & Security and grant:

   • Accessibility — required for window management, mouse/keyboard input, and the ax_* accessibility tools.
   • Screen Recording — required for capture, capture_region, capture_window, and list_capturable_windows.
   • Full Disk Access — only needed if you point MACCTL_ALLOWED_PATHS outside your user-visible home folders.

3. Restart the host app (Claude Desktop, your terminal, etc.) after granting. macOS does not apply a fresh TCC grant to an already-running process.

You can also trigger the native grant dialogs directly instead of only getting deep links:

npx @sitharaj88/macctl doctor --prompt

Tools that hit a missing permission at runtime return a structured PERMISSION_MISSING error with the same "which app, which permission, which link" detail — call system_doctor again after granting to confirm.

Installation

Claude Desktop (recommended)

Download the latest macctl.mcpb from GitHub Releases and double-click it. The bundled helper binary is Developer ID signed and notarized, so Gatekeeper accepts it without extra steps on a fresh download.

Claude Code

claude mcp add macctl -- npx -y @sitharaj88/macctl

Manual MCP client configuration

Add an entry to your client's MCP server config (Claude Desktop's claude_desktop_config.json, or the equivalent for your client):

{
  "mcpServers": {
    "macctl": {
      "command": "npx",
      "args": ["-y", "@sitharaj88/macctl"]
    }
  }
}

Then follow Grant permissions above and restart the client.

Permission tiers & profiles

Every tool belongs to exactly one tier. A tool in a disabled tier is never registered with the MCP client — this is an allowlist enforced at tools/list time, not a runtime check the model could talk its way around.

| Tier | Covers | |---|---| | observe | Read-only: screenshots, window/AX inspection, system/process info, file reads. | | interact | Mouse/keyboard input, window focus/move/close, AX actions, clipboard. | | filesystem | Writing, deleting, moving, and creating files/directories. | | manage | Process start/kill, launchd service control, notifications. | | shell | Arbitrary shell commands via shell_run — unsandboxed, runs with the host process's own OS permissions. |

Profiles bundle tiers together:

| Profile | Tiers enabled | |---|---| | readonly | observe | | standard (default) | observe, interact, filesystem | | full | observe, interact, filesystem, manage, shell |

system_doctor is always registered regardless of profile — it's how you diagnose everything else.

Set the profile via MACCTL_PROFILE, or bypass profiles entirely with an explicit tier list via MACCTL_TIERS (e.g. MACCTL_TIERS=observe,interact), which overrides the profile's tier set completely rather than adding to it.

MACCTL_PROFILE=readonly npx @sitharaj88/macctl        # observation only
MACCTL_PROFILE=full npx @sitharaj88/macctl             # everything, incl. shell
MACCTL_TIERS=observe,interact npx @sitharaj88/macctl   # explicit override

Configuration

All configuration is via environment variables, read once at startup:

| Variable | Default | Description | |---|---|---| | MACCTL_PROFILE | standard | readonly | standard | full. See profiles above. | | MACCTL_TIERS | (unset) | Comma-separated tier list (observe,interact,filesystem,manage,shell) that, if set, replaces the profile's tier set entirely. | | MACCTL_ALLOWED_PATHS | (unset → home dir, /tmp, /private/tmp, /Volumes) | Colon-separated (:) list of directories file/exec-path tools are confined to. | | MACCTL_DENIED_PATHS | (unset) | Colon-separated (:) list of additional directories to deny, layered on top of the built-in denylist (~/Library/Keychains, ~/.ssh, ~/Library/Application Support/com.apple.TCC, ~/Library/Containers, ~/Library/Group Containers, ~/Library/Cookies, ~/Library/Safari, ~/Library/Mail, /private/var/db). Denied always wins over allowed. | | MACCTL_CONFIRM_DESTRUCTIVE | true | If true, destructive tools require an explicit confirm: true argument. Set to 0/false/no/off to disable. | | MACCTL_AUDIT_LOG | ~/Library/Logs/macctl/audit.jsonl | Path to the audit log file. | | MACCTL_AUDIT_DISABLED | false | Disable audit logging entirely. | | MACCTL_MAX_IMAGE_WIDTH | 1600 | Screenshots wider than this (in pixels) are downscaled by the helper before being returned. | | MACCTL_COMMAND_TIMEOUT_MS | 60000 | Default timeout for shell_run, overridable per call. | | MACCTL_HELPER_PATH | (unset → auto-resolved next to the installed package, native/bin/macctl-helper) | Explicit path to the native helper binary — mainly for local development (scripts/build-helper.sh --dev). |

Complete tool reference

41 tools total. Tier is shown per tool; destructive tools additionally require confirm: true when MACCTL_CONFIRM_DESTRUCTIVE is enabled (the default).

Doctor (always registered, any profile)

| Tool | Tier | Description | |---|---|---| | system_doctor | observe | TCC permission status, responsible app, native helper reachability, active profile/tiers, audit log location, version info. |

Screen (5)

| Tool | Tier | Description | |---|---|---| | list_monitors | observe | List connected displays with frame, visible frame, backing scale factor, and which is main. | | capture | observe | Screenshot a full display (main by default). | | capture_region | observe | Screenshot a rectangular region in global screen points. | | capture_window | observe | Screenshot a single window by windowHandle. | | list_capturable_windows | observe | List on-screen windows available for capture_window, via ScreenCaptureKit. |

Windows (7)

| Tool | Tier | Description | |---|---|---| | window_list | observe | List all on-screen windows with title, owning app, pid, bounds, layer, minimized state, and a windowHandle. | | window_get_active | observe | Get the frontmost app and its focused window. | | window_get_desktop_info | observe | Get screen layout, light/dark appearance, and cursor position. | | window_focus | interact | Activate a window's owning app and raise the window. | | window_set_state | interact | Minimize, restore, maximize, fullscreen, hide, or show a window. | | window_move | interact | Move and/or resize a window; returns the verified final frame. | | window_close | interact, destructive | Close a window by pressing its AXCloseButton. |

Input (7)

| Tool | Tier | Description | |---|---|---| | input_move_mouse | interact | Move the mouse cursor to a global screen point. | | input_click | interact | Click at a global screen point (left/right/middle, single/double/triple). | | input_drag | interact | Press, drag through interpolated points, and release. | | input_scroll | interact | Post a scroll-wheel event, optionally moving the cursor first. | | input_type | interact | Type Unicode text at the current keyboard focus (layout-independent; paste for long text). | | input_press_keys | interact | Press a keyboard chord, e.g. "cmd+shift+4". | | input_key_hold | interact | Hold a single key down or release it (auto-releases after 30s). |

Accessibility (4)

| Tool | Tier | Description | |---|---|---| | ax_snapshot | observe | Walk the AXUIElement tree of an app or window (role/title/value/description/identifier/enabled/frame per node). | | ax_find | observe | Bounded search over an app's/window's tree by role, title/value substring, and/or identifier. | | ax_invoke | interact | Perform an accessibility action on an element (default AXPress). | | ax_set_value | interact | Set an element's value directly, or via focus + Cmd+A + type fallback, with verified read-back. |

System & Processes (8)

| Tool | Tier | Description | |---|---|---| | system_info | observe | CPU, memory, disk, network, battery, graphics, macOS version, hardware model. | | list_services | observe | List launchd services: running (launchctl list) joined with installed LaunchAgents/LaunchDaemons. | | list_installed_apps | observe | List installed applications: name, bundle id, version, path. | | process_list | observe | List running processes (pid, ppid, cpu%, mem%, rss, elapsed, command). | | control_service | manage, destructive | Restart/stop/start/enable/disable a launchd LaunchAgent. LaunchDaemons (system domain) refuse with PRIVILEGE_REQUIRED. | | notify | manage | Show a macOS notification banner. | | process_start | manage | Launch an app (open -a/open -b), open a document/URL, or spawn a bare executable. | | process_kill | manage, destructive | Terminate a process by pid (SIGTERM, optionally escalating to SIGKILL). |

Files, Clipboard & Shell (9)

| Tool | Tier | Description | |---|---|---| | file_known_folders | observe | List well-known macOS folders (home, Desktop, Documents, Downloads, iCloud Drive, etc.) with existence/allow-list status. | | file_list | observe | List a directory's entries, optionally recursive with a depth cap. | | file_read | observe | Read a file as utf8 text or base64, capped at maxBytes. | | file_search | observe | Search a directory tree by name glob and/or content regex, or accelerated via mdfind. | | file_write | filesystem, destructive | Write, append to, or create a text/base64 file. | | file_manage | filesystem, destructive | Copy, move, delete a file/directory, or mkdir -p. | | clipboard_read | interact | Read clipboard text, file references, and image presence. | | clipboard_write | interact | Replace clipboard contents with text or file references. | | shell_run | shell | Run a command via /bin/zsh -c, capturing stdout/stderr/exit code. |

Example workflow

A realistic multi-tool sequence — opening TextEdit, finding its text area via the accessibility tree (not coordinates), typing, and verifying visually:

1. process_start        { app: "TextEdit" }
2. window_get_active     → windowHandle for the new TextEdit window
3. ax_find                { windowHandle, role: "AXTextArea" }
                          → elementHandle for the document's text area
4. ax_invoke               { elementHandle }              # focus/click it
5. input_type              { text: "Meeting notes...\n\n- Discuss Q3 roadmap" }
6. ax_snapshot              { windowHandle, maxDepth: 5 }  # read the value back, verify it landed
7. capture_window           { windowHandle }               # visual confirmation
8. window_move               { windowHandle, x: 100, y: 100 }
9. input_press_keys           { keys: "cmd+s" }              # save
10. window_close                { windowHandle, confirm: true }  # destructive — needs confirm

Each step uses a real tool name and an opaque handle produced by an earlier step — never a guessed coordinate or a raw pointer.

Safety & audit

• Destructive-action confirmation. window_close, file_write, file_manage, control_service, and process_kill are marked destructive. When MACCTL_CONFIRM_DESTRUCTIVE is enabled (the default), each call must include confirm: true or it's refused with CONFIRMATION_REQUIRED — no first-try accidental deletes.
• Path containment. File and executable-path tools resolve the real (symlink-followed) path and check it against MACCTL_ALLOWED_PATHS / MACCTL_DENIED_PATHS, with a built-in denylist (Keychains, ~/.ssh, TCC store, app containers, Safari/Mail data, /private/var/db) that always wins over anything allowed.
• No silent privilege escalation. macctl never shells out to sudo. Actions that would need elevated privileges (e.g. controlling a system-domain LaunchDaemon) fail honestly with PRIVILEGE_REQUIRED rather than prompting for or assuming root.
• Audit log. Every tool call is appended as one JSON line to ~/Library/Logs/macctl/audit.jsonl (configurable, or disable with MACCTL_AUDIT_DISABLED=1): timestamp, tool name, outcome, duration, error code, and redacted arguments (long strings and base64-looking blobs are replaced with [redacted N chars] before being written).

Privacy

See PRIVACY.md for the full policy. In short: macctl runs entirely locally and has no telemetry. Screenshots, accessibility-tree contents, clipboard data, and file contents are returned only to the MCP client that requested them — nothing is sent anywhere by macctl itself.

Development

git clone https://github.com/sitharaj88/macctl.git
cd macctl
npm install
npm run build:all        # tsc + universal Swift helper build (native/bin/macctl-helper)

npm run build:helper (via scripts/build-helper.sh) builds the Swift helper as a universal (arm64 + x86_64) binary using Swift Package Manager; run it with --dev for a fast, current-arch-only build during local iteration.

npm run smoke             # spawns the server, exercises TCC-free tools across all 3 profiles
npm run smoke:full        # also exercises TCC-dependent tools (skips gracefully if ungranted)
node scripts/verify-interactive.mjs   # full TextEdit round-trip — needs a real GUI session + Accessibility/Screen Recording grants

verify-interactive.mjs drives an actual TextEdit window end-to-end (open → find the text area → type → read the value back → screenshot → move → close), so it must run in a real logged-in GUI session with permissions already granted to your terminal — it will not work over SSH or in CI.

Publishing

• npm: npm publish --access public
• .mcpb bundle: npx @anthropic-ai/mcpb pack (respects .mcpbignore; produces macctl.mcpb for GitHub Releases / Claude Desktop's drag-and-drop install).
• MCP registry: mcp-publisher publish (using server.json).

👤 Author

Sitharaj Seenivasan

• 🌐 Website: sitharaj.in
• 💼 LinkedIn: sitharaj08
• 💻 GitHub: sitharaj88

☕ Support

If this project helps you, consider buying me a coffee — it keeps the work going.

📄 License

Licensed under the Apache License 2.0. © 2026 Sitharaj Seenivasan.