Computer Use MCP

Computer Use MCP is a local, window-scoped computer-control server for macOS. It exposes a conservative Model Context Protocol (MCP) tool surface that can be launched by Codex, Claude Desktop, Claude Code, Cursor, MCP Inspector, or any other stdio-capable MCP host.

Alpha status: v0.1.0-alpha.1 is the prepared source-only security-preview release candidate; it has not been tagged or published yet. It does not include a prebuilt, signed, or notarized macOS application. Review the code, build it locally, and use it only with non-sensitive data while the interfaces and safety controls are still changing.

What makes it different

• Access is granted to one selected window (or, only when explicitly requested, one display), not implicitly to the whole desktop.

• A persisted General app access switch defaults to off. When off, the native host fails closed for operations that could inspect or control another app; status and Stop remain available.

• Every observation and action is checked against a short-lived local capability and the current window owner, process, and identity.

• A non-activating control rail appears on the left edge of the controlled window. It shows the requester identity that the native bridge derived from the nearest verifiable GUI process ancestor (or Unidentified local MCP harness), mode, and target; Stop immediately revokes active access.

• Screen Recording and Accessibility are requested separately and remain under macOS System Settings. The application cannot silently grant them to itself.

• Remembering an approved signed app never chooses a target. Every new grant still requires an exact window choice; display grants are always session-only.

• The native host uses public ScreenCaptureKit, Accessibility, and Core Graphics APIs. The optional targeted private-driver path is disabled by default, version-gated, and fails closed when unavailable.

• Risk classification and one-shot challenge binding live in the native host. Modern clients collect the user's decision through MCP elicitation; clients without elicitation use the native approval panel.

• Screenshots and typed text are not written to the audit log. See Privacy for the exact defaults.

Related MCP server: mcp-server-macos-use

Architecture

Codex / Claude / Cursor / Inspector / another MCP host
                         |
                    MCP over stdio
                         |
          @jmeguilos/computer-use-mcp
                         |
             private child-process pipes
                         |
        signed ComputerUseMCPBridge helper
                         |
       authenticated local Unix-domain socket
                         |
              Computer Use MCP Host.app
            /              |              \
 ScreenCaptureKit   Accessibility/CGEvent   left-edge indicator

The Node.js process is a protocol adapter. It spawns the locally signed native bridge over private child pipes; only that bridge may authenticate to the host's socket in the release architecture. Before forwarding the first hello, the bridge independently verifies the socket peer's kernel UID/PID/audit token and pins it to the sibling host executable path and signing requirement; release mode also requires the expected host bundle and Developer ID team. The native host owns macOS TCC permissions, window selection, grants, capture, input, the visible indicator, and the audit trail. The boundary is intentional: an MCP process never receives ambient authority merely because a client launched it. Bridge signing proves which code connected to the socket; it does not prove which same-user harness invoked that bridge. The bridge ignores caller-supplied names and instance IDs and derives requester attribution from the nearest verifiable GUI process ancestor, binding its PID, bundle ID, signing identity, and process generation. That attribution describes observed process ancestry; it is not caller authorization. Exact native target consent and risk-based action approval remain mandatory for every caller.

Read Architecture, Protocol, and the Threat model before extending the control surface.

Requirements

• macOS 14.4 or later

• Node.js 20 or later and npm

• Xcode 16 or later, or matching Command Line Tools with Swift 6

• A local interactive login session (not SSH-only, a launch daemon, or a locked screen)

Build the alpha from source

git clone https://github.com/jmeguilos/computer-use-mcp.git
cd computer-use-mcp
npm ci
npm run build
npm run swift:build
npm run setup
npm run doctor

setup builds both native executables, installs an explicitly development-only ad-hoc-signed app in the current user's Applications directory, and launches the original first-run settings window. It never edits the TCC database or uses sudo. doctor is read-only: it reports versions, paths, host reachability, socket permissions, TCC state, and packaging problems without changing permissions.

For the original first-run window and its controls, see Onboarding and settings. For the complete source-build and permission flow, see Setup. Contributors should also read Local development.

Connect an MCP client

Build first, then use the absolute path to the generated stdio entry point:

/ABSOLUTE/PATH/TO/computer-use-mcp/packages/mcp/dist/index.js

For example, Codex can register the source build with:

codex mcp add computer-use-mcp -- \
  node /ABSOLUTE/PATH/TO/computer-use-mcp/packages/mcp/dist/index.js

Current, copyable configurations are in Client compatibility and examples/. Those instructions were last checked against each vendor's official documentation on 2026-08-29.

Safety model in one minute

1. The client starts the stdio adapter.

2. The adapter spawns the native bridge over private pipes. The host verifies the bridge's peer UID/PID and socket audit token before issuing a connection capability over a mode-0600 Unix-domain socket inside a mode-0700 runtime directory. Before sending hello, the bridge verifies the host peer's kernel identity and pins it to the sibling host executable path and signing requirement. Developer ID-signed releases additionally enforce the expected bundle and team identity in both directions. Those checks reject unsigned release replacements, but any same-user program can launch the genuine bridge and request a connection. This alpha's ad-hoc-signed source-development mode also permits same-user direct peers. In both modes, the caller remains untrusted until the native host grants an exact target and, when required, one exact action. On the normal bridge path, caller-provided names and instance IDs are discarded; the bridge attributes the request to the nearest verifiable GUI process ancestor, or reports Unidentified local MCP harness when it cannot derive one. An unidentified harness may inspect status and inventory, but all inventory entries remain non-grantable and target requests are denied before the native picker opens.

3. On first run, the native settings window keeps General app access off until the user enables it and reports Screen Recording and Accessibility as two separate macOS decisions. Turning the switch on grants no target authority.

4. computer_request_access opens native UI. The user chooses an exact window and capabilities, then allows that target, optionally remembers its verified app identity, or denies the request. A remembered app still requires an exact window choice. A separately requested display is session-only and can never be remembered.

5. The host binds a grant to the connection and selected target identity. It revalidates that identity before every capture and action.

6. The indicator stays visible while a grant is active. Stop, window closure, target replacement, session lock, timeout, or client disconnect revokes it.

System Screen Recording permission is necessarily broader than one window. The project's per-window boundary is therefore an application-enforced capability, not a claim that macOS TCC itself is window-scoped. See the Threat model.

Use Stop on the target indicator, or Emergency Stop in the host's menu-bar item, before taking over manually. V1 does not monitor global user input and does not support control while the session is locked; lock or sleep revokes active authority.

Tools

The alpha exposes exactly 15 tools covering discovery/status, grant lifecycle, state capture, pointer, keyboard, scrolling, semantic Accessibility actions, and clipboard writes. The authoritative list and request/response rules live in Protocol. Tools fail closed when a grant is absent, stale, or does not contain the required capability.

Release policy

v0.1.0-alpha.1 is prepared for source-only GitHub distribution with checksums, an SBOM, and an inspectable npm pack artifact, but no public release has been created yet. Nothing is published to the npm registry. The Developer ID, hardened-runtime, and notarization workflow is disabled by default and requires an explicitly protected release environment. See Releasing.

Contributing and security

Contributions must satisfy the clean-room provenance policy and pass the automated provenance gate. Please read CONTRIBUTING.md before opening a pull request.

Do not report vulnerabilities in a public issue. Follow SECURITY.md instead.

License

Copyright 2026 jmeguilos and contributors. Licensed under the Apache License 2.0. See NOTICE and third-party notices.

Apple, Anthropic, Claude, Cursor, OpenAI, and Codex are trademarks of their respective owners. This independent project is not endorsed by or affiliated with those companies.