Mac MCP 2.1.1

Mac MCP is a local macOS control server for AI agents. It exposes your Mac through a native MCP endpoint and a REST/OpenAPI surface, with shell, files, browser automation, macOS UI control, delegated OpenCode/Codex agents, memory, Agent Skills, voice interaction, self-update tooling, and a local operations dashboard.

Security: Mac MCP can execute commands, read/write files, and control desktop apps. Keep MCP authentication enabled whenever the service is reachable outside localhost and expose it only to clients you trust. The operations dashboard is loopback-only and requires a separate per-user dashboard Bearer token; localhost is machine-local transport, not a same-user sandbox.

What's new in 2.1.1

• Added the Safari Visual Companion, a bundled Safari Web Extension that makes real Mac MCP browser work visible inside the exact page being automated. While an agent is working, Safari can show a subtle animated page frame, Mac MCP · … activity badge, synthetic cursor movement, and click feedback.

• Visual feedback is driven by the existing high-level browser actions, including Inspecting, Finding, Reading, Clicking, Typing, Selecting, Focusing, and Scrolling. It works with the same real Safari tabs used by Mac MCP; it does not replace the browser automation layer or require a separate browser profile.

• The visual event channel is intentionally metadata-only: it sends a bounded action label, optional viewport coordinates, effect type, and TTL. Typed text, selectors, URLs, titles, DOM content, and secrets are not copied into extension events.

• Added a native Safari Activity card to Mac MCP.app. Registered Apple-signed builds offer Enable in Safari…; local ad-hoc builds now show Developer Setup… instead of failing when Safari has not registered the extension.

• The installer and updater carry the Safari extension with the menu app and verify the nested extension signature. The installer now distinguishes a normal Apple-signed distribution from an ad-hoc local source build and prints the correct Safari setup for each.

• Kept the overlay display-only. It is useful for watching what an agent is doing, but it is not a trust, permission, or security indicator; Mac MCP's existing access profiles, approvals, provenance, secret-egress guard, tab leases, and no-progress protections remain authoritative.

• The 2.1 release also includes the recent browser resilience and security work: source-aware web-to-host approval, secret-egress protection, sticky untrusted provenance, no-progress circuit breaking, delegated tab leases, steering idempotency/recovery, and dedicated-user hardening guidance.

Related MCP server: macos-mcp

What's new in 2.0.5

• Mac MCP now presents a 21-tool core surface by default instead of sending the full tool catalog to every MCP client. The complete registry remains available through tool_discover + tool_invoke, so older capabilities are not removed.

• The registered capability set is now 84 tools total: the previous 81 tools plus browser_do, tool_discover, and tool_invoke. All previous 81 tools remain callable.

• Added browser_do for one-call browser transactions: open a URL, wait, interact, extract targeted fields, optionally verify state, and optionally close the newly opened tab without extra MCP round trips.

• Added targeted browser extract actions so agents can request only the data they need instead of pulling large DOM/HTML payloads into context.

• browser_find and browser_act are now part of the default core surface; visual observations retain compact DOM IDs alongside the image, and semantic browser extraction is more resilient on dynamic pages such as Google Maps.

• Reduced default browser observation payloads and disabled macOS screenshots by default for mac_observe, cutting unnecessary context and capture work.

• Hardened network_idle waits against Safari's transient about:blank state and preserved normal risk/profile enforcement for dynamically invoked tools.

• In local compatibility testing, tool-schema context fell from about 16.7k to 4.5k tokens (~73% less) while all previous 81 tools retained an access path.

• Set MAC_MCP_TOOL_PROFILE=full if a client explicitly needs the entire registered catalog advertised up front.

What's new in 2.0

• Native Mac MCP.app menu bar controller written in SwiftUI. It runs without a Dock icon and remains independent from the Python server.

• Start, Stop, Restart, Update, Dashboard, server status, ngrok status, success rate, recent tool usage, and delegated-agent status are available from the menu bar.

• Latest Tool Usage shows up to five rows at once and scrolls internally for older calls.

• Delegated Agents keeps a compact fixed-height list and scrolls internally when multiple active/recent agents exist. Active work also triggers a lightweight animated robot and a pulsing menu bar status icon.

• Live agent steering adds persistent logical Sessions to the menu bar, so you can redirect a specific agent while it is working or queue a new instruction while it is idle without sending the prompt to the wrong conversation.

• The menu bar treats dashboard reachability as a first-class state: Connected, Degraded, Disconnected, or Connecting. Failed fetches never masquerade as an empty session list; the last successful session snapshot is retained and marked stale until a successful refresh replaces it.

• Polling uses bounded exponential backoff after failures (1s → 2s → 4s → 8s → 16s → 30s max) and resets to the normal 2.5-second interval after recovery. A manual Retry performs an immediate refresh.

• Voice is a collapsed disclosure section by default. ask_user_voice can be enabled/disabled live without removing the MCP tool from discovery.

• When voice is disabled, calls return experimental_tool_disabled and instruct the agent to fall back to ask_user.

• Groq API keys can be stored in macOS Keychain instead of plaintext configuration.

• Voice input/output pickers enumerate connected CoreAudio devices such as AirPods, built-in microphone, and speakers.

• Runtime settings are read live from ~/.mac-mcp/settings.json; voice changes do not require an MCP restart.

• The updater now carries the native menu_app/ runtime alongside mcp_server/ and refreshes an already-installed menu app after updates.

Browser automation that doesn't hijack your Mac

Mac MCP can inspect and interact with Safari and Chrome tabs in the background while you keep working in another app or browser tab. Here, background means a normal, visible Safari/Chrome tab that Mac MCP controls without bringing the browser or tab to the front; it is not a hidden/headless browser session.

• New browser tabs open in the background by default and return a stable tab_handle.

• Stable tab handles survive tab-index changes, so long-running tasks keep targeting the intended Safari or Chrome tab even as other tabs open, close, or move.

• browser_observe can return compact DOM context plus viewport, element, or full-page visuals without activating the browser, switching tabs, scrolling the user's page, or leaving screenshot files on disk.

• High-level browser actions can target a specific background tab directly by handle, which makes parallel research and delegated-agent workflows practical without constant focus stealing.

• Foreground-only fallbacks such as native key presses and absolute coordinate clicks fail closed unless foreground access is explicitly requested.

• The native menu bar controller surfaces live browser work in Sessions and Latest Tool Usage with a privacy-minimized browser/site/action summary. URL paths, query strings, page titles, selectors, and page content are intentionally omitted from this compact view.

• Show Tab is an explicit user action: normal automation remains non-focus-stealing, while clicking Show Tab brings that specific real Safari/Chrome tab to the front.

This is designed for workflows where an AI agent keeps working in one or more background browser tabs while the Mac remains usable normally.

Safari Visual Companion

Mac MCP.app bundles a Safari Web Extension that makes active Mac MCP browser work visible inside the exact page being automated. The extension is display-only: it renders a subtle pulsing page frame, a small Mac MCP · … activity badge, a synthetic cursor, and click feedback for high-level browser actions. Visual events contain only bounded action labels and viewport coordinates; typed text, selectors, URLs, page titles, DOM content, and secrets are not copied into the extension event. The overlay is activity feedback only and must not be treated as a security or trust indicator.

Safari setup depends on how Mac MCP.app is signed:

Developer ID / Apple-signed build (persistent):

1. Install or update Mac MCP normally.

2. Open Mac MCP.app → Safari Activity → Enable in Safari…. You can also use Safari → Settings → Extensions.

3. Turn on Mac MCP Visual Companion and grant website access for the sites where you want activity feedback.

Local GitHub/source build (ad-hoc, development mode):

1. Open Mac MCP.app → Safari Activity → Developer Setup…. Mac MCP reveals the packaged extension Resources folder and opens Safari.

2. In Safari, enable web-developer features if the Develop menu is hidden.

3. Choose Develop → Allow Unsigned Extensions.

4. Choose Develop → Add Temporary Extension… and select ~/Applications/Mac MCP.app/Contents/PlugIns/Mac MCP Safari Visual Companion.appex/Contents/Resources.

5. Grant website access when Safari asks. Safari treats this as a development/temporary extension; persistent normal installation requires an Apple-signed app bundle.

The project remains fully open source and does not need the Mac App Store. For a persistent GitHub release, sign/notarize the distributed Mac MCP.app with Developer ID; menu_app/build_app.sh accepts MAC_MCP_CODESIGN_IDENTITY for that release path.

No separate browser profile, helper daemon, or Xcode project is required. menu_app/build_app.sh compiles the .appex into Mac MCP.app/Contents/PlugIns/ with the normal command-line Swift toolchain. Local builds default to ad-hoc signing; release builders can set MAC_MCP_CODESIGN_IDENTITY to use a Developer ID identity with hardened runtime/timestamp signing.

Requirements

• macOS 13+

• Apple Silicon or Intel Mac

• Python 3.10+

• Git

• Xcode Command Line Tools (swiftc)

• ngrok only if you want a public HTTPS MCP endpoint

brew install python git ngrok

Optional helpers:

brew install cliclick brightness

Install

Recommended: one-line installer

The easiest way to install Mac MCP on a new Mac is the interactive installer:

curl -fsSL https://raw.githubusercontent.com/bulutarkan/mac-mcp/main/install.sh | bash

The installer is designed specifically to work safely through curl | bash while still reading interactive answers from the real terminal. It:

• verifies macOS 13+, Apple Silicon or Intel, Git, Python 3.10+, Xcode Command Line Tools, and swiftc;

• can offer Homebrew when a required dependency is missing, while keeping optional helpers such as cliclick and brightness optional;

• creates a Git source checkout at ~/Projects/mac-mcp and a separate runtime at ~/mac-mcp without Git metadata;

• creates and verifies the Python virtual environment and dependencies;

• generates a strong MCP API key, enables authenticated access, and stores the runtime .env with mode 600;

• installs the mac-mcp CLI at ~/.local/bin/mac-mcp and records the deployed commit for the built-in updater;

• builds and code-sign verifies the native Mac MCP.app menu bar controller in ~/Applications;

• shows both Bearer-token and ?ApiKey= connection formats at the end;

• does not install OpenCode or Codex. If you want to use Subagents, install either provider separately.

Existing source/runtime/CLI paths are never silently overwritten. If Mac MCP is already installed, use the built-in updater instead of re-running the installer over the same paths.

Manual installation

If you prefer to manage the checkout and Python environment yourself:

git clone https://github.com/bulutarkan/mac-mcp.git
cd mac-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp mcp_server/.env.example mcp_server/.env

Configure at minimum:

MCP_API_KEY=replace-with-a-long-random-token
MCP_ALLOW_NO_AUTH=false
MCP_ALLOW_SHELL=true
RATE_LIMIT_PER_MINUTE=120

# Optional public tunnel
NGROK_DOMAIN=your-domain.ngrok-free.dev

Generate a strong token:

python3 - <<'PY'
import secrets
print(secrets.token_urlsafe(48))
PY

When authentication is enabled, the preferred client credential is still:

Authorization: Bearer <MCP_API_KEY>

For MCP clients/connectors that cannot set an Authorization header, Mac MCP also accepts the configured global key in the endpoint URL:

https://your-domain.example/mcp?ApiKey=<MCP_API_KEY>

Authorization remains authoritative when both forms are supplied. Empty, duplicate, or invalid ApiKey query credentials are rejected while authentication is enabled. The server removes ApiKey from its local access-log URL before logging, but upstream proxies/tunnels can still observe query strings, so Bearer headers should be preferred whenever the client supports them.

Product and security terminology

Mac MCP uses a small canonical glossary so UI and documentation do not imply stronger isolation or invisibility than the product actually provides. See docs/TERMINOLOGY.md for the full definitions.

• Background browser automation: visible, non-focus-stealing Safari/Chrome automation; not hidden or headless.

• Capability: whether the Mac MCP server policy permits a tool/risk class.

• Approval: a human-confirmation mechanism and its source; separate from capability enforcement.

• Localhost / loopback: machine-local transport, not same-user isolation or a sandbox.

• Mac MCP logical session: a local hashed steering identity that keeps one agent/conversation flow coherent; not the raw provider identity.

• Dedicated user: containment/hardening that reduces blast radius; not a complete sandbox.

For an advanced two-account deployment, see Hardened deployment with a dedicated non-admin macOS user. It covers loopback authentication, an explicit ACL-shared directory, TCC/GUI-session limits, tool behavior, rollback, and a two-user validation matrix.

Permission profiles and approval semantics

Mac MCP treats capability enforcement and human approval as separate security concepts. A capability being allowed means only that the Mac MCP server policy permits that tool/risk class. It does not mean a second confirmation prompt will appear before the action runs.

ask_confirmation remains an explicit interaction tool and is not a blanket confirmation wrapper around normal tool calls. Separately, Mac MCP has narrow server-side security gates for risky trust-boundary crossings. Under standard and scoped delegated profiles, an untrusted web context → privileged host action can require a source-aware Allow Once / Block decision. The global trusted profile intentionally skips that routine web→host confirmation so trusted interactive workflows are not interrupted on every shell/file/UI hop. Detected credential/secret egress to an untrusted origin remains source-aware and approval-gated even under trusted. Exact-action grants remain origin-bound and single-use.

Delegated Codex workers currently run with Codex approval_policy="never"; their sandbox/access mode is separate from human approval. OpenCode permission behavior is also provider-side and must not be treated as a Mac MCP server confirmation guarantee.

Set the server capability profile with MAC_MCP_PERMISSION_PROFILE=trusted|standard|read_only. The native menu bar app reads /dashboard/api/security/semantics and shows Allowed Capabilities and Approval Behavior separately for the active profile. The three preset rows are clickable: choosing one persists the value in mcp_server/.env and applies it to new global requests immediately without restarting the server or ngrok. Existing delegated agents keep the scoped profile issued when they were started; new agents inherit the newly selected parent profile.

Browser resilience guards are configurable with MAC_MCP_NO_PROGRESS_THRESHOLD (default 4, range 2–10) and MAC_MCP_TAB_LEASE_TTL_S (default 300 seconds, range 30–3600). The no-progress breaker stops only repeated meaningful browser actions that fail to change DOM revision, URL, or title; wait/scroll/extract flows do not consume that budget. Delegated-agent tab ownership is logical and time-bounded: completing/cancelling/crashing an agent releases ownership without closing the user's tab, and the next agent must make a fresh browser_observe before acting on a previously owned handle.

Untrusted web provenance is sticky at the logical-session level. Once a session consumes third-party browser content, writing that content to a local scratch file, reading it back, closing the tab, or passing through unrelated read-only tools does not erase that provenance. Scoped/non-trusted workflows continue through the web→host security gate until the work moves to an independent clean-room session. The global trusted profile keeps the sticky provenance for audit and secret-egress checks but does not show a routine Allow Once dialog for each normal privileged host hop. Delegated children spawned from a tainted session inherit the taint metadata (origin, reason, and credential fingerprints) without copying raw DOM or secrets into the security log; nested delegation preserves the inheritance chain. A genuinely independent MCP session with no transferred payload starts clean under the normal policy.

Install the menu bar app

./menu_app/install_app.sh

Default location:

~/Applications/Mac MCP.app

The app is independent from the server:

• quitting the app does not stop MCP;

• stopping MCP does not quit the app;

• mac-mcp start opens the app automatically when it is installed;

• server controls remain available even while the Voice section is collapsed.

The app uses the localhost dashboard APIs with a separate dashboard Bearer credential stored in ~/.mac-mcp/dashboard-token (mode 0600). The menu app reads that owner-only file locally and never needs the global MCP_API_KEY:

/dashboard/api/summary
/dashboard/api/security/semantics
/dashboard/api/events
/dashboard/api/agents
/dashboard/api/steering

Live menu-bar steering

Mac MCP keeps a Mac MCP logical session visible between tool calls instead of showing it only for the few milliseconds while a tool is running. It prefers stable conversation metadata supplied by the MCP client (for example OpenAI's conversation-scoped openai/session metadata), then generic _meta.client_id, and finally a reused stateful Streamable HTTP transport as a fallback. Raw identity values are hashed before entering steering state and are never exposed in the dashboard. This matters for hosts that create a fresh transport session for every tool call: repeated calls from the same conversation still collapse into one Working / Idle agent card.

Steering messages are kept in memory only and are bound to the selected logical agent, never to a global "next caller" queue. If the selected agent currently has a tool running, the prompt is appended to that tool's live response as structured _mac_mcp_steering content. If the agent is idle, the prompt remains queued for that logical session and its next requested tool is preempted before execution with a mac_mcp_steering_preempted tool error, so the agent sees the user's new direction before doing more work. A different conversation/session cannot consume that prompt. Logical steering sessions expire after 10 minutes of inactivity by default. The menu-bar Sessions disclosure lets you enter any positive number of minutes and persists that value in ~/.mac-mcp/settings.json; stateful protocol transports are separately bounded so short-lived client transports do not accumulate indefinitely. Raw steering text is not written into telemetry SQLite, and nested fallback calls such as tool_invoke do not create duplicate visible sessions.

Steering POST acceptance is idempotent for clients that send client_instruction_id. The menu app generates a UUID for each Send action and reuses that same UUID for a bounded retry when the HTTP result is ambiguous. Replaying the same session + client ID + text returns the original canonical st_* message instead of enqueuing a duplicate; reusing a client ID with different text or another live session returns 409 idempotency_conflict. Recent lifecycle rows include the client correlation ID so the menu app can recover an accepted message after a lost response. Legacy clients that omit client_instruction_id keep the original enqueue behavior. The in-memory idempotency index is bounded and is discarded with the logical session TTL.

For example, if an agent is researching with visible, non-focus-stealing browser automation in a Safari tab and you type stop using Airbnb and check Booking.com instead into that agent's Session, Mac MCP routes the instruction only to that logical agent. A running tool can return the steering immediately; an idle agent is interrupted before its next tool call so it can change course first.

SwiftUI state update efficiency

The native controller remains @MainActor and keeps the same polling cadence, but it publishes decoded dashboard values only when they actually change. Session snapshots are diffed by stable session_id before replacing the observable array, preserving SwiftUI row identity and avoiding hierarchy invalidation for identical polls. Volatile duration updates are coalesced only while their rendered label would remain unchanged. This is a rendering/state-efficiency optimization, not a slower-refresh mode.

Sessions information architecture

The menu bar derives three deterministic sections from the versioned lifecycle snapshot: Needs Attention (failed, unresolved/unknown, or recent disconnected/expired session events), Active (working, queued, delivered, pending, or awaiting acknowledgement), and Recent (retained idle ready/acknowledged sessions). Historical terminal rows are informational rather than steerable. The menu-bar status icon carries only an aggregate attention/active signal. Mac MCP does not show session Retry/Cancel controls because no such backend actions exist; connection Retry remains a separate dashboard-reachability action.

Versioned session lifecycle

The steering API exposes schema_version: 1 and separates activity from instruction lifecycle. Legacy state=working|idle and queued fields remain for compatibility; new clients should prefer activity_state, lifecycle_state, pending_instruction_count, last_transition_at, and last_error.

The instruction lifecycle is intentionally small: ready → queued → delivered → acknowledged. If the underlying tool fails before queued steering can be delivered, the session enters failed while keeping the instruction pending for the next tool call. Transport-backed sessions emit disconnected when their MCP transport disappears, and idle sessions emit expired when their retention TTL elapses. Illegal lifecycle transitions are rejected internally instead of silently producing ambiguous state.

acknowledged is inferred when the same logical agent makes its next top-level tool request after receiving steering; it means the agent continued after the delivery boundary, not that the model sent a separate acknowledgement packet. Daemon/API reachability is a different connection concern and is handled separately by the menu app's connection UX.

Menu bar connection resilience

The native controller does not treat a failed dashboard request as valid empty data. A successful empty /dashboard/api/steering response clears the session list normally; an HTTP error, timeout, or connection refusal preserves the last successful snapshot and marks it stale. If the app has never received a valid session snapshot, it shows Session data unavailable rather than No agent sessions yet.

A transport failure such as timeout or connection refusal enters disconnected; an HTTP error or invalid response from a reachable server enters degraded, including failures from the primary summary endpoint. HTTP status failures, timeouts, and connection-refused errors are surfaced separately. Automatic polling backs off from 1 second to a 30-second cap and returns to the normal 2.5-second cadence after the next complete successful refresh.

Server commands

mac-mcp start
mac-mcp start --ngrok
mac-mcp status
mac-mcp restart --ngrok
mac-mcp stop
mac-mcp dashboard

Default local endpoint:

http://127.0.0.1:8000/mcp

A custom port can be supplied through MAC_MCP_PORT or CLI flags.

Voice interaction

ask_user_voice speaks a short prompt, records the local answer, transcribes it with Groq Whisper, and returns the transcript to the calling agent.

The menu app manages:

• experimental enable/disable toggle;

• Groq API key in macOS Keychain;

• input microphone;

• output device;

• language;

• timeout;

• TTS voice and rate.

Non-secret settings are stored in:

~/.mac-mcp/settings.json

Environment variables remain supported as fallbacks, including MAC_MCP_VOICE_GROQ_API_KEY, GROQ_API_KEY, MAC_MCP_VOICE_LANGUAGE, MAC_MCP_VOICE_INPUT_DEVICE, MAC_MCP_VOICE_OUTPUT_DEVICE, and MAC_MCP_VOICE_TTS_RATE.

Operations dashboard

Open it with the authenticated local launcher:

mac-mcp dashboard

The static dashboard shell is loopback-only. Every sensitive /dashboard/api/* request and the live /dashboard/events stream additionally require a separate dashboard Bearer token stored at ~/.mac-mcp/dashboard-token with mode 0600; the state directory is kept owner-only (0700). The CLI/menu app passes the browser credential in a URL fragment, which is not sent in the HTTP request, and dashboard JavaScript immediately moves it to sessionStorage, removes it from the address bar, and uses an Authorization header for API/SSE requests. The global connector MCP_API_KEY is not exposed to the browser.

The dashboard records sanitized MCP/REST tool activity, status, latency, recent delegated-agent state, active calls, and tool frequency. Provider identity fields such as OpenAI session/subject/organization/location are dropped from telemetry; the security migration also scrubs legacy persisted rows on first startup. Telemetry persists locally under:

~/.mac-mcp/dashboard/telemetry.sqlite3

Loopback means machine-local, not user-private. The dashboard token prevents unrelated unauthenticated local processes and browser-origin requests from using sensitive endpoints, but a malicious process already running as the same macOS user can generally read that user's files and is inside this trust boundary. Unix-domain sockets were evaluated for menu-app ↔ daemon traffic; they can provide filesystem-owner permissions but do not solve same-UID isolation and cannot be consumed directly by the browser dashboard, so authenticated loopback HTTP remains the single transport. See docs/LOCAL_API_SECURITY.md for the threat model and decision.

Tool coverage

Mac MCP 2.1 advertises a compact 21-tool core surface by default, backed by 84 registered MCP capabilities. The 63 less-common tools remain available through tool_discover and tool_invoke, including every tool from the previous 81-tool surface.

Set MAC_MCP_TOOL_PROFILE=full to advertise all registered tools directly to the client. You can also add selected tools to the compact surface with MAC_MCP_CORE_EXTRA_TOOLS=name1,name2.

The capability set covers:

• terminal/system and background jobs;

• delegated OpenCode/Codex agents;

• file management;

• macOS automation and Accessibility UI control;

• Safari/Chrome browser automation with stable tab handles and background visual observation;

• HTTP and search;

• text/choice/confirmation/voice human input;

• persistent memory;

• Agent Skills;

• safe self-update.

Use MCP tool discovery for the authoritative live schema.

Updating

mac-mcp update --check
mac-mcp update

The updater follows origin/main, blocks on dirty repositories, preserves runtime overlays and private files, creates a runtime backup, restarts the managed service, performs a health check, and rolls back managed runtime files if verification fails.

In 2.0, menu_app/ is part of the managed runtime. If Mac MCP.app is already installed, a successful update rebuilds and refreshes it automatically.

macOS permissions

Grant only the permissions required by the tools you use:

• Accessibility for mac_observe, mac_act, System Events, and desktop automation;

• Screen Recording for protected screen capture;

• Automation when macOS asks permission to control Safari, Chrome, System Events, Reminders, or other apps;

• Microphone for ask_user_voice.

Development

Run tests:

python -m unittest discover -s tests -v

Build the native menu app without installing it:

./menu_app/build_app.sh /tmp/mac-mcp-build

Project layout:

mcp_server/   Python MCP server and dashboard
menu_app/     Native SwiftUI menu bar controller
tests/        Regression tests
openapi/      REST/OpenAPI schema assets

License

MIT