AXTerminator

MCP server that gives AI agents the ability to see and control macOS applications.

Deploy · MCP Tools · CLI · Query Syntax · Troubleshooting · Wiki · Known Limitations

Up to 34+ MCP tools (27 core + optional audio, camera, spaces). Background interaction via the macOS Accessibility API. 379us per element access. Audio capture, camera input, virtual desktop isolation. Your AI agent connects and your Mac becomes an extension of it.

Platform scope. AX-first-with-vision-fallback is macOS-only. iOS/iPadOS support is tracked in #43 as a future capability and, when shipped, will be screenshot + vision only — the idevice/RPPairing surface does not expose AX trees for third-party apps, and UIAutomation would require an on-device test runner (breaks the "mac-only agent, no on-device prereqs" contract). Reported screenshot latency via CoreDeviceProxy: ~350ms USB, ~700ms WiFi (credit @m13v). tvOS is unverified — the RSD surface is narrower than idevice's tvOS target suggests; please open an issue with device evidence if you've tested. See #42 for the AX-first-vs-vision-first positioning rationale.

Deploy

Tell your AI assistant (recommended):

Read https://github.com/MikkoParkkola/axterminator and install axterminator as my macOS GUI automation MCP server

Your agent will install the binary, wire itself up, and request accessibility permissions. Works in Claude Code, Cursor, Windsurf, and any AI with terminal access.

Or install manually:

brew install MikkoParkkola/tap/axterminator

Grant accessibility permissions: System Settings > Privacy & Security > Accessibility (add your terminal app).

axterminator mcp install auto-detects your AI client. Specify one with --client:

axterminator mcp install                       # Claude Desktop (default)
axterminator mcp install --client claude-code  # Claude Code
axterminator mcp install --client cursor       # Cursor
axterminator mcp install --client windsurf     # Windsurf
axterminator mcp install --client codex        # OpenAI Codex CLI
axterminator mcp install --client vscode       # VS Code Copilot
axterminator mcp install --client zed          # Zed
axterminator mcp install --dry-run             # Preview without writing

Also supported: gemini, amazon-q, lm-studio.

# From crates.io
cargo install axterminator --features cli

# Build from source
git clone https://github.com/MikkoParkkola/axterminator
cd axterminator
cargo build --release --features cli

# Manual JSON (Claude Desktop, Cursor, Windsurf, etc.)
# { "mcpServers": { "axterminator": { "command": "axterminator", "args": ["mcp", "serve"] } } }

For Codex (~/.codex/config.toml):

[mcp_servers.axterminator]
command = "axterminator"
args = ["mcp", "serve"]

Done. Your agent has 27 core tools (up to 34+ with all feature flags) to control any macOS app.

MCP Tools

Resources

Agents can browse app state without tool calls:

Security

Destructive actions require confirmation via elicitation. HTTP transport requires bearer token auth. The AI has hands, not root.

CLI

axterminator apps                        # List accessible apps
axterminator find "Save" --app Safari    # Find element
axterminator click "Save" --app Safari   # Click it
axterminator screenshot --app Safari     # Capture screenshot
axterminator tree --app Finder           # Element hierarchy
axterminator mcp serve --http 8080 --token secret  # HTTP transport

Query Syntax

# Simple text — matches ANY of: title, description, value, label, identifier
axterminator find "Save" --app Safari

# By role
axterminator find "role:AXButton" --app Safari

# Combined role + attribute (AND)
axterminator find "role:AXButton title:Save" --app Safari

# By description (useful for apps like Calculator)
axterminator find "description:equals" --app Calculator

# By value
axterminator find "value:42" --app Calculator

# XPath-like
axterminator find "//AXButton[@AXTitle='Save']" --app Safari

How It Works

AXTerminator uses an undocumented behavior of Apple's Accessibility API: AXUIElementPerformAction() works on unfocused windows. Your agent clicks buttons in one app while you work in another. Neither notices.

379us per element access (Criterion, M1 MacBook Pro). Appium needs 500ms for the same thing.

7-strategy self-healing locators survive UI changes: data_testid, aria_label, identifier, title, xpath, position, visual_vlm.

Known Limitations

Platform coverage (see #43):

Troubleshooting

AI agents: Fetch llms.txt for machine-readable installation instructions.

Feature Flags

The Homebrew formula includes all features. When building from source, select capabilities with feature flags:

cargo build --release --features "cli,audio,camera,spaces"

Community

• Wiki -- Full documentation
• Discussions -- Questions, ideas, show-and-tell
• Issues -- Bugs

Acknowledgements

Inspired by Terminator by mediar-ai, which pioneered accessible desktop GUI automation on Windows.

For AI Agents

Machine-readable installation guide: llms.txt

Your agent can fetch this URL to get step-by-step installation, MCP config for every host, and troubleshooting.

Ecosystem

axterminator is part of a suite of MCP tools:

License

MIT OR Apache-2.0