Apple Productivity MCP

Apple Productivity MCP

A local macOS MCP server for working with Apple's productivity apps, documents, files, and media from Codex, Claude Code, Claude Desktop, and other stdio MCP clients.

Version 3.0.0: 133 tools across 17 groups, plus optional execution of explicitly allowlisted Shortcuts. Runs on your Mac through Apple's automation interfaces. No hosted service, listening port, subscription, or Apple API key is required.

Tool reference · Machine-readable schemas · Verification · Source documentation · Changelog · Publishing · Directory status

What it can do

The original 18 tool names remain supported. Version 3 expands the default catalog; select only the app groups you want below.

Coverage has boundaries. Apple does not expose every app feature through scripting. Messages history, Contacts deletion, Pages layout text boxes, full document styling, Calendar invitations, Reminders subtasks/tags/recurrence, arbitrary Safari JavaScript, and private Apple databases are not implemented. There are no dedicated Home, Health, Wallet, Find My, or Freeform editing tools. A user-created, allowlisted Shortcut can bridge supported actions in other apps. The complete input schemas describe exactly what each tool accepts.

Requirements

• macOS and Node.js 20 or newer.
• The Apple app you want to control must be installed and configured. Pages, Numbers, and Keynote are separate App Store installations.
• A client supporting local stdio MCP servers.
• macOS Automation permission for the launching client/process to control each app. Some file locations also require Files & Folders access.

The server starts when the MCP client connects. Each automation call uses a fixed script and JSON arguments with a timeout. iCloud, Exchange, or other account sync continues to follow the app's own settings.

Install

Codex

codex mcp add apple-productivity-local -- \

npx -y @gambadio/apple-productivity-mcp@latest codex mcp get apple-productivity-local

Claude Code

claude mcp add --transport stdio --scope user apple-productivity-local -- \

npx -y @gambadio/apple-productivity-mcp@latest claude mcp get apple-productivity-local

Claude Desktop and other JSON-configured clients

Add this to the client's MCP configuration, then restart it:

{

"mcpServers": { "apple-productivity-local": { "command": "npx", "args": ["-y", "@gambadio/apple-productivity-mcp@latest"] } } }

For a reproducible install, replace @latest with @3.0.0. A tested local .mcpb bundle and checksum are available in the GitHub release. See the packaging instructions to build one yourself. This package requires execution on the user's Mac and cannot access their apps from a Linux container or remote hosting service.

Configuration

All settings are optional. Put them in your MCP client's server environment and start a new MCP process.

Example with Notes, reminders, files, and one permitted Shortcut:

{

"mcpServers": { "apple-productivity-local": { "command": "npx", "args": ["-y", "@gambadio/apple-productivity-mcp@3.0.0"], "env": { "APPLE_MCP_ENABLED_GROUPS": "system,notes,reminders,files,finder,shortcuts", "APPLE_MCP_FILE_ROOTS": "[\"/Users/YOUR_NAME/Documents\"]", "APPLE_MCP_SHORTCUTS": "[\"Prepare daily note\"]" } } } }

Replace YOUR_NAME and the shortcut name with values that exist on your Mac. An iCloud Drive directory can be included using its real local absolute path.

File roots constrain the generic file tools listed above; they are not a sandbox for Apple apps. iWork/TextEdit open/save/export and Photos import/export use explicit paths under the macOS permissions of those apps. Shortcuts may perform any action already contained in the allowed shortcut, including sending messages or changing data elsewhere. Inspect a shortcut before allowlisting it. App-group filtering and read-only mode control the exposed tool surface; MCP annotations are hints for clients, not an authorization system.

Example requests

• “Find reminders with ‘invoice’ in the title, then show their notes and due dates.”
• “Create a Notes folder in this account and put my meeting summary in it.”
• “Read this Pages document and export a PDF beside it.”
• “List the sheets and tables in my Numbers workbook, then fill cells B2:D6 with these values.”
• “Add a Keynote slide with this title, body, and presenter notes.”
• “Find Mail messages from this sender and save the selected attachment in my allowed Documents folder.”
• “List my Photos albums and export these selected items into an empty folder.”
• “Run my allowlisted ‘Prepare daily note’ shortcut.”

Start with discovery tools. Use returned IDs/names and inspect the tool schema for exact fields. apple_system_capabilities identifies installed apps but does not pre-authorize them or prove permissions. Write requests act on real data, so name the intended target and changes explicitly.

Data handling and safeguards

• No server-side account, telemetry service, network listener, or credential storage.
• Fixed JXA programs receive user values as JSON arguments, without interpolation into executable source. There is no arbitrary code or shell execution tool.
• New file copies refuse replacement. Text writes and document save/export require an explicit overwrite option to replace a path. Photos exports require an empty folder.
• Generic file operations require explicit roots and check resolved paths. File deletion goes through Finder Trash; there is no empty-Trash tool.
• Collection reads and text/cell ranges have limits. Locked Notes are not read or modified. Safari tab mutations compare the expected URL to guard against shifted indices.
• Read-only mode hides mutations. Every tool declares read-only, destructive, idempotent, and open-world annotations.
• Email, Messages, document changes, reminders, contacts, and media edits may sync or reach other people. A send result means submission to the app, not independently verified delivery.
• Timeouts or multi-step errors can leave partial changes. Inspect the target before retrying a write.
• Data returned to an MCP client becomes part of that client's active model session and is governed by its data controls. Local execution does not mean content stays outside the model session. JSON inputs are visible to local processes with sufficient OS privileges.

Development and verification

npm ci

npm test npm run docs:tools npm audit --omit=dev npm pack --dry-run

Tests execute the static automation programs against application fixtures, exercise filesystem boundaries in temporary folders, and initialize the actual stdio MCP server. They do not send messages or edit personal app data.

For the existing read-only Mail/Calendar/Reminders integration suite, after granting Automation permission:

npm run test:integration

Live verification is app-specific. Pages, Numbers, and Keynote were not installed on the release development Mac; their tools have fixture coverage but no live iWork verification. See verification results and limitations and implementation sources. Do not interpret the tool count as a claim that every operation has been exercised against every app/macOS version.

Troubleshooting

Automation unavailable / not authorized / timeout: open System Settings → Privacy & Security → Automation and permit the relevant Apple app for the launching client. A timeout can also reflect a busy app or slow iCloud data; do not blindly retry writes. Restart the client after permission/configuration changes.

Application cannot be found: install the app, launch it once, and verify apple_system_capabilities. OS process sandboxing can also restrict LaunchServices. Run a local client with the appropriate macOS access.

File roots required / path outside allowed roots: configure APPLE_MCP_FILE_ROOTS as a JSON array of existing absolute directories. A symlink cannot be used to escape that list. Create missing parent folders first.

Object not found / ambiguous name: rediscover the app's current account, list, document, or object ID. Names differ by language/provider. Close or rename duplicate documents before editing by name.

Contacts has unsaved changes: save or discard your pending edits in Contacts before using a mutation, because Contacts' scripting save affects all pending changes.

Tools missing: check app-group/read-only settings, start a new session, and verify mcp get/mcp list in your client. Shortcut execution appears only with a nonempty allowlist. Apps need not be installed for their tools to be advertised.

`spawn ... ENOENT`: ensure Node and npx are accessible to the desktop client's PATH; use the fu