Metadata-Version: 2.4
Name: drews-mac-control-mcp
Version: 0.2.44
Summary: An MCP server that lets an LLM drive macOS apps and the iOS Simulator, delivered as a signed macOS app.
Author-email: Andrew Benson <db@nuclearcyborg.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/drewster99/drews-mac-control-mcp
Project-URL: Source, https://github.com/drewster99/drews-mac-control-mcp
Project-URL: Issues, https://github.com/drewster99/drews-mac-control-mcp/issues
Keywords: mcp,model-context-protocol,macos,accessibility,automation,ios-simulator
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Drew's Mac Control MCP Server

An MCP server that lets an LLM inspect and drive macOS apps and the iOS Simulator through the
Accessibility API — click, type, read the element hierarchy, capture screenshots, pick menu items,
drive the Simulator.

This package is a thin wrapper. The server itself is a **signed, notarized macOS app**; the wheel
carries that bundle and installs it to `~/Applications` on first run, then hands off to the
`MacControlRelay` binary inside it. Later releases replace the installed app automatically, so
`uvx` upgrades keep the app in step with the wrapper.

## Install

```sh
uvx drews-mac-control-mcp --setup
```

That installs the app, opens it so macOS prompts for permissions, and prints the client
registration command.

Two approvals are needed, and both are easy to miss:

1. **A new background item.** Registering the host creates a login item, and macOS asks about it.
   Dismissing that prompt leaves the agent unapproved, so the host never starts and every tool call
   fails with nothing to explain why. If you dismissed it, enable **MacControlMCP** under
   System Settings ▸ General ▸ Login Items & Extensions.
2. **Accessibility** — and **Screen Recording** if you want screenshots — in
   System Settings ▸ Privacy & Security.

Then register **this wrapper** as the MCP server command:

```sh
claude mcp add --scope user maccontrol -- "$(command -v uvx)" drews-mac-control-mcp
codex  mcp add maccontrol -- "$(command -v uvx)" drews-mac-control-mcp
```

That is what keeps it current. On every launch the wrapper checks the app installed in
`~/Applications` against the version this wheel carries and replaces it if they differ. `uvx`
supplies the other half: it caches PyPI's index for the ten minutes PyPI asks for and re-resolves
once that lapses, so a new release arrives on its own — within minutes, not necessarily on the very
next call. `uvx --refresh drews-mac-control-mcp` forces it immediately.

Pointing a client straight at `~/Applications/MacControlMCP.app/Contents/Helpers/MacControlRelay`
also works, but it pins you to whatever is installed today and silently forfeits every future
update.

## Uninstall

```sh
uvx drews-mac-control-mcp --uninstall
```

Removes the host agent's registration **first**, then the app. That order is the point: deleting
the bundle on its own does not clear its registration, which leaves a login item pointing at an app
that is gone and only findable by hand in System Settings. If the registration cannot be removed,
nothing is deleted — pressing on is exactly what strands it.

## Requirements

macOS 14 or later. The wheel is tagged `macosx_14_0_universal2`, so pip and uv decline to install
it anywhere else.

## Source

<https://github.com/drewster99/drews-mac-control-mcp> — including how to build and install from a
checkout instead, which needs Xcode and your own Developer ID.

## License

[Apache License 2.0](https://github.com/drewster99/drews-mac-control-mcp/blob/main/LICENSE).
