Macos-MCP
About
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.
Explore
- Works with Any LLM (Vision Optional)
Unlike traditional automation tools, macOS-MCP doesn't require computer vision, fine-tuned models, or specialized setup. Works seamlessly with any LLM—Claude, GPT, Gemini, or others.
- Native macOS Integration
Interacts natively with macOS UI elements using the Accessibility API. Opens apps, controls windows, simulates user input, and captures desktop state without workarounds.
- Rich Toolset for Automation
Complete toolkit for keyboard/mouse operations, window management, UI state capture, interactive element extraction from the accessibility tree, and AppleScript execution.
- Lightweight and Open-Source
Minimal dependencies with full source code available under MIT license. Easy setup and deployment.
- Smart Context Awareness
Automatically detects application state (Launchpad, Control Center, Spotlight). Scans menu bar, dock, desktop, and system UI elements intelligently.
- Customizable and Extensible
Easily extend with custom tools or modify behavior to suit your specific automation needs.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Macos-MCPCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
- Python: 3.11 or later
- UV Package Manager: Install with pip install uv or curl -LsSf https://astral.sh/uv/install.sh | sh
- macOS: 12 (Monterey) or later
- Accessibility Permissions: Required for UI element interaction
macos-mcp --transport sse --host 0.0.0.0 --auth-key "your_token"
Authorization: Bearer your_token header on all requests.
Instead of passing flags every time, store your configuration in ~/.macos-mcp/config.toml. CLI flags always override config file values.
Search order:
1. --config /path/to/config.toml
2. ~/.macos-mcp/config.toml
stdio — local only, no security needed:
[server]
transport = "stdio"
SSE — network access with auth and IP restriction:
[server]
transport = "sse"
host = "0.0.0.0"
port = 8000
auth_key = "your-secret-key"
[security]
ip_allowlist = ["192.168.1.0/24"]
Streamable HTTP — network access with auth and TLS (recommended for production):
[server]
transport = "streamable-http"
host = "0.0.0.0"
port = 8000
auth_key = "your-secret-key"
ssl_certfile = "cert.pem" # resolved relative to ~/.macos-mcp/
ssl_keyfile = "key.pem"
[security]
ip_allowlist = ["192.168.1.0/24"]
oauth_client_id = "my-client" # optional — enables OAuth 2.0 + PKCE
oauth_client_secret = "my-secret"
[tools]
exclude = ["Shell", "Scrape"] # disable specific tools
Available tool names: App, Shell, Snapshot, Click, Type, Scroll, Move, Shortcut, Wait, Scrape, Notification
Place your cert and key files in the same directory:
~/.macos-mcp/
├── config.toml
├── cert.pem
└── key.pem
Generate a self-signed cert directly into that directory:
mkdir -p ~/.macos-mcp
openssl req -x509 -newkey rsa:4096 \
-keyout ~/.macos-mcp/key.pem \
-out ~/.macos-mcp/cert.pem \
-days 365 -nodes
---
All variables are optional. Set them via the env key in claude_desktop_config.json.
| Variable | Default | Description |
|---|---|---|
| ANONYMIZED_TELEMETRY | true | Set to false to disable anonymous usage telemetry. No personal data, tool arguments, or outputs are ever collected. |
| MACOS_MCP_AUTH_KEY | _(none)_ | Bearer token required on all HTTP requests. Alternative to --auth-key CLI flag. |
| MACOS_MCP_IP_ALLOWLIST | _(none)_ | Comma-separated list of allowed client IPs or CIDR ranges. Alternative to --ip-allowlist CLI flag. |
| MACOS_MCP_SSL_CERTFILE | _(none)_ | Path to TLS certificate file (.pem). Must be provided with MACOS_MCP_SSL_KEYFILE. |
| MACOS_MCP_SSL_KEYFILE | _(none)_ | Path to TLS private key file (.pem). Must be provided with MACOS_MCP_SSL_CERTFILE. |
Example claude_desktop_config.json (remote with auth + TLS):
{
"mcpServers": {
"macos-mcp": {
"command": "uvx",
"args": ["macos-mcp", "--transport", "sse", "--host", "0.0.0.0"],
"env": {
"MACOS_MCP_AUTH_KEY": "your_token",
"MACOS_MCP_IP_ALLOWLIST": "203.0.113.0/24",
"MACOS_MCP_SSL_CERTFILE": "/path/to/cert.pem",
"MACOS_MCP_SSL_KEYFILE": "/path/to/key.pem"
}
}
}
}
---
macOS-MCP provides a comprehensive toolset for desktop automation:
| Tool | Purpose |
|------|---------|
| Click | Click at coordinates with support for left, right, and double-click |
| Type | Type text at cursor position, optionally clearing existing text |
| Scroll | Scroll vertically or horizontally in focused window or regions |
| Move | Move mouse pointer or drag to coordinates |
| Shortcut | Press keyboard shortcuts (Cmd+C, Cmd+Tab, etc.) |
| App | Launch applications, manage windows (resize/move), switch between apps. Supports app names and bundle IDs |
| Shell | Execute commands or AppleScript. Use mode='osascript' for AppleScript |
| Scrape | Extract and convert webpage content to Markdown format |
| Wait | Pause execution for a defined duration |
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"macos-mcp": {
"macos-mcp": {
"command": "uvx",
"args": [
"macos-mcp"
]
}
}
}
}McpServers
{
"macos-mcp": {
"command": "uvx",
"args": [
"macos-mcp"
]
}
}Config File (~/.macos-mcp/config.toml)
Instead of passing flags every time, store your configuration in ~/.macos-mcp/config.toml. CLI flags always override config file values.
Search order:
1. --config /path/to/config.toml
2. ~/.macos-mcp/config.toml
stdio — local only, no security needed:
[server]
transport = "stdio"
SSE — network access with auth and IP restriction:
[server]
transport = "sse"
host = "0.0.0.0"
port = 8000
auth_key = "your-secret-key"
[security]
ip_allowlist = ["192.168.1.0/24"]
Streamable HTTP — network access with auth and TLS (recommended for production):
[server]
transport = "streamable-http"
host = "0.0.0.0"
port = 8000
auth_key = "your-secret-key"
ssl_certfile = "cert.pem" # resolved relative to ~/.macos-mcp/
ssl_keyfile = "key.pem"
[security]
ip_allowlist = ["192.168.1.0/24"]
oauth_client_id = "my-client" # optional — enables OAuth 2.0 + PKCE
oauth_client_secret = "my-secret"
[tools]
exclude = ["Shell", "Scrape"] # disable specific tools
Available tool names: App, Shell, Snapshot, Click, Type, Scroll, Move, Shortcut, Wait, Scrape, Notification
Place your cert and key files in the same directory:
~/.macos-mcp/
├── config.toml
├── cert.pem
└── key.pem
Generate a self-signed cert directly into that directory:
mkdir -p ~/.macos-mcp
openssl req -x509 -newkey rsa:4096 \
-keyout ~/.macos-mcp/key.pem \
-out ~/.macos-mcp/cert.pem \
-days 365 -nodes
---
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
