Documentation

MacPilot docs

Everything you need to install, configure, and use MacPilot with Claude Desktop.

Getting Started

MacPilot is an MCP (Model Context Protocol) server for macOS. Once installed, it registers itself with Claude Desktop and exposes 46+ tools that give Claude native control over your Mac.

Prerequisites

  • •macOS 14 Sonoma or later (Apple Silicon or Intel)
  • •Claude Desktop installed (download free)
  • •Accessibility permissions granted to MacPilot (prompted on first launch)

Quick install

  1. 1. Download MacPilot.dmg
  2. 2. Drag MacPilot to /Applications
  3. 3. Launch MacPilot — it auto-registers with Claude Desktop
  4. 4. Open Claude Desktop and start automating

MCP Tools Reference

MacPilot exposes the following tools to Claude. Free tier includes all core tools. Pro/Max tiers unlock additional automation skills.

⌘

App Control

macpilot_launch_app

Launch an application by name or bundle ID

macpilot_quit_app

Quit a running application

macpilot_list_apps

List all running applications

macpilot_focus_app

Bring an application to the foreground

⊞

Window Management

macpilot_list_windows

List all open windows

macpilot_move_window

Move a window to specific coordinates

macpilot_resize_window

Resize a window to given dimensions

macpilot_close_window

Close a specific window

⌨

Keyboard & Mouse

macpilot_type_text

Type text into the focused element

macpilot_key_press

Send a keyboard shortcut or key combination

macpilot_mouse_click

Click at screen coordinates

macpilot_mouse_move

Move the cursor to coordinates

⊙

Screen & UI

macpilot_screenshot

Capture a screenshot of the screen or a window

macpilot_ocr_screen

Extract text from the screen via OCR

macpilot_find_element

Find a UI element by label or role

macpilot_click_element

Click a UI element by accessibility path

📁

File System

macpilot_read_file

Read the contents of a file

macpilot_write_file

Write or overwrite a file

macpilot_list_directory

List files in a directory

macpilot_move_file

Move or rename a file

⬡

Scripting

macpilot_run_applescript

Execute an AppleScript snippet

macpilot_run_shell

Run a shell command and return output

macpilot_open_url

Open a URL in the default browser

License Keys

MacPilot uses a UUID-based license key system. Your key is stored locally at ~/.macpilot/license.json and validated against the license server on startup.

Getting a license key

Visit the pricing page and enter your email to generate a free license key. No credit card required for the Free tier.

Configuration

MacPilot writes its MCP server config to Claude Desktop automatically on first launch. The config file is located at:

~/Library/Application Support/Claude/claude_desktop_config.json

Troubleshooting

Tools not appearing in Claude Desktop

Quit and relaunch MacPilot, then restart Claude Desktop. MacPilot must be running for tools to appear.

Accessibility permission errors

Go to System Settings → Privacy & Security → Accessibility and ensure MacPilot is enabled.

License validation fails

Check your internet connection. If the issue persists, re-enter your license key in MacPilot settings.