Mac Mcp

Mac MCP 2.0

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 authentication enabled whenever the service is reachable outside localhost and expose it only to clients you trust. The operations dashboard is loopback-only.

What's new in 2.0.5

• Mac MCP now presents a 19-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.
• 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.
• 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.

• 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.

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

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

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 - /dashboard

The dashboard records sanitized MCP/REST tool activity, status, latency, recent delegated-agent state, active calls, and tool frequency. Telemetry persists locally under:

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

The dashboard is restricted to loopback access even when /mcp is exposed through ngrok.

Tool coverage

Mac MCP 2.0.5 advertises a compact 19-tool core surface by default, backed by 84 registered MCP capabilities. The 65 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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bulutarkan
• Source: bulutarkan/mac-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.