# Add to your Claude Code skills
git clone https://github.com/CursorTouch/MacOS-MCPGuides for using mcp servers skills like MacOS-MCP.
MacOS-MCP is an open-source mcp servers skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by CursorTouch. Lightweight MCP server for computer use in MacOS. It has 100 GitHub stars.
MacOS-MCP's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/CursorTouch/MacOS-MCP" and add it to your Claude Code skills directory (see the Installation section above).
MacOS-MCP is primarily written in Python. It is open-source under CursorTouch on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other MCP Servers skills you can browse and compare side by side. Open the MCP Servers category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh MacOS-MCP against similar tools.
No comments yet. Be the first to share your thoughts!
Unlocks once the catalog security scan passes (runs nightly).
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
macOS-MCP is a lightweight, open-source Model Context Protocol server that bridges AI agents and the macOS operating system. It enables seamless automation of macOS through LLMs via tasks such as file navigation, application control, UI interaction, browser automation, and system operations.
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.
pip install uv or curl -LsSf https://astral.sh/uv/install.sh | shRun the server directly:
uvx macos-mcp
# Or with SSE/Streamable HTTP for network access
uvx macos-mcp --transport sse --host localhost --port 8000
uvx macos-mcp --transport streamable-http --host localhost --port 8000
Run it as a background service that starts now and at every login:
macos-mcp install
# Or choose the HTTP transport and bind address explicitly
macos-mcp install --transport sse --host 127.0.0.1 --port 8000
This installs a launchd Launch Agent at ~/Library/LaunchAgents/com.macos-mcp.server.plist.
Use macos-mcp uninstall to remove it. Logs are written to ~/.macos-mcp/server.log
and ~/.macos-mcp/server.error.log.
| Transport | Flag | Use Case |
|---|---|---|
stdio (default) |
--transport stdio |
Direct connection from MCP clients like Claude Desktop, Cursor, etc. |
sse |
--transport sse --host HOST --port PORT |
Network-accessible via Server-Sent Events |
streamable-http |
--transport streamable-http --host HOST --port PORT |
Network-accessible via HTTP streaming (recommended for production) |
macOS-MCP requires Accessibility and Screen Recording permissions to function properly.
/usr/bin/python3 or the Python version managed by UV)~/.local/bin/uv if installed locally, or the Python environment UV manages)For uvx users: Grant permissions to your terminal application and Python, as uvx runs Python packages from UV's cache.
The Snapshot tool requires Screen Recording permissions to capture screenshots:
Note: If the Snapshot tool fails, verify both permissions are granted in System Settings.
Install Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"macos-mcp": {
"command": "uvx",
"args": ["macos-mcp"]
}
}
}
npm install -g @google/gemini-cli
Navigate to ~/.gemini and open settings.json
Add the server config:
{
"theme": "Default",
"mcpServers": {
"macos-mcp": {
"command": "uvx",
"args": ["macos-mcp"]
}
}
}
Install Claude Code
Add to your project configuration or use the MCP marketplace integration
Pi does not ship with built-in MCP support, but macOS-MCP can be installed as a Pi package. The package starts this MCP server over stdio and exposes convenient Pi tools that wrap the existing macOS-MCP tools.
One-line global setup:
pi install git:github.com/CursorTouch/MacOS-MCP
After install, restart Pi or run:
/reload
Try without installing:
pi -e git:github.com/CursorTouch/MacOS-MCP
Local checkout setup:
git clone https://github.com/CursorTouch/MacOS-MCP.git
cd MacOS-MCP
uv sync
npm install
pi
If you copied only the extension into another Pi project, run Pi from the macOS-MCP checkout or set:
export MACOS_MCP_ROOT=/path/to/MacOS-MCP
The extension exposes these Pi tools:
| Pi Tool | Purpose |
|---|---|
mac_snapshot |
Read current macOS UI state through the existing Snapshot tool. |
mac_app |
Launch, switch, move, or resize macOS applications/windows. |
mac_click |
Click coordinates returned by mac_snapshot. |
mac_type |
Type text at coordinates returned by mac_snapshot. |
mac_shortcut |
Run keyboard shortcuts such as command+c or command+space. |
mac_scroll |
Scroll at the current pointer or coordinates. |
mac_wait |
Wait for UI changes/loading. |
Recommended agent workflow:
mac_snapshot first.mac_click, mac_type, and mac_scroll.The extension auto-detects the macOS-MCP checkout when installed as a Pi package. If you use a manually copied extension, set MACOS_MCP_ROOT=/path/to/MacOS-MCP.
Any client supporting the Model Context Protocol can integrate macOS-MCP by configuring the uvx macos-mcp command in their MCP server settings.
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 |
macos-mcp --transport sse --host 0.0.0.0 --auth-key "your_token"
Requires Authorization: Bearer your_token header on all requests.
macos-mcp --auth-key "token" --ip-allowlist "203.0.113.0/24,198.51.100.5"
Restricts connections to specified CIDR ranges.
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
macos-mcp --ssl-certfile cert.pem --ssl-keyfile key.pem
For MCP clients that use OAuth (e.g. Claude Desktop) instead of a static API key:
macos-mcp --transport streamable-http --host 0.0.0.0 \
--ssl-certfile ~/.macos-mcp/cert.pem \
--ssl-keyfile ~/.macos-mcp/key.pem \
--oauth-client-id my-client \
--oauth-client-secret my-secret
Claude Desktop config:
{
"mcpServers": {
"macos-mcp": {
"type": "http",
"url": "https://<host>:8000/mcp/",
"oauth": {