Macos-MCP

What is Macos-MCP?

Macos-MCP is a lightweight, open‑source Model Context Protocol server that bridges AI agents and the macOS operating system. It enables LLMs to automate tasks such as file navigation, application control, UI interaction, browser automation, and system operations on macOS.

How to use Macos-MCP?

Install Python 3.11+, the UV package manager, and ensure macOS 12+. Run the server with uvx macos-mcp (stdio transport) or with --transport sse or --transport streamable-http for network access. Optionally install it as a background service using macos-mcp install. Grant Accessibility and Screen Recording permissions in System Settings. Integrate with MCP clients like Claude Desktop, Gemini CLI, Claude Code, or Pi Agent by adding the uvx macos-mcp command to the client’s MCP server configuration.

Key features of Macos-MCP

• Works with any LLM; no computer vision required.
• Native macOS integration via the Accessibility API.
• Rich toolset for keyboard, mouse, window, and UI automation.
• Lightweight, open-source, and easy to deploy.
• Smart context awareness of docks, menus, and system UI.
• Customizable and extensible with additional tools.

Use cases of Macos-MCP

• Automate repetitive UI tasks like clicking, typing, and scrolling.
• Launch, switch, resize, and manage application windows programmatically.
• Execute shell commands or AppleScript from an AI assistant.
• Capture and read the current macOS UI state (snapshot) for context.
• Scrape web page content and convert it to Markdown.

FAQ from Macos-MCP

What are the system requirements?

macOS 12 (Monterey) or later, Python 3.11+, and the UV package manager. Accessibility and Screen Recording permissions must be granted manually.

Does Macos-MCP require an API key or special model?

No. It works with any LLM and does not require a computer vision model, fine‑tuning, or API keys for local use. For network transports, an optional authentication key can be set.

How do I grant the necessary permissions?

Open System Settings → Privacy & Security → Accessibility, add your terminal, Python, and UV executables, then restart the terminal. For the Snapshot tool, also grant Screen Recording permissions to the same applications.

Can Macos-MCP be used over a network?

Yes. Use the --transport sse or --transport streamable-http flags to expose the server over HTTP. Security features like auth keys, IP allowlists, TLS, and OAuth 2.0 + PKCE are available.

What are the main limitations?

Manual permission grants are required. Some apps have limited Accessibility API support. Complex UIs may slow traversal. Certain text fields may not receive keystrokes. System authentication dialogs cannot be automated.