Apple Tools (Unified)

Apple-Tools-MCP

Unified MCP server for Apple apps on macOS.

One entrypoint for Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System, and Maps. This server wraps the standalone servers and exposes a unified MCP interface.

What It Does

• Read context across multiple Apple apps
• Unified actions across all apps
• Prompts for day planning, communications triage, and meeting prep
• Persistent defaults for mail, calendar, reminders, notes, and communication routing
• Per-contact preferences for people who always route a specific way
• Helper workflows for communication routing, archiving mail, capturing follow-ups, and collaboration summaries
• Mail thread helpers and Contacts method editing in one place
• Preview, audit, and undo for reversible actions
• Files-aware attachment and document workflows within scoped roots
• System-aware workflows using the frontmost app, clipboard, notifications, running apps, and assistant-relevant macOS settings
• Truthful Focus context and combined system snapshots for briefing and routing
• Explicit macOS settings writes for appearance, Finder, Dock, and key accessibility preferences
• Bounded GUI fallback tools when a native app-domain MCP cannot complete a task directly
• Finder-aware file workflows, Finder tags, recent locations, and iCloud Drive awareness through Apple Files
• Travel-aware workflows using Apple Maps for place search and route estimates
• Daily briefing, weekly briefing, and communications-triage tools
• Prompt fallback via apple_list_prompts and apple_get_prompt
• One install target instead of ten separate configurations

When to use

• Personal assistant workflows across multiple Apple apps
• Cross-app operations (e.g., Calendar and Reminders together)
• Simpler setup without wiring each standalone MCP separately

Tool Discovery

Apple-Tools-MCP exposes its full tool surface through tools/list, with readOnlyHint/destructiveHint annotations and structured output schemas — modern clients defer-load large tool surfaces themselves. For context-constrained clients:

• search_tools finds tools by name, aliases, and domain tags
• get_tool_info loads the full schema and examples for one tool on demand
• generated code-mode wrappers are exported under generated/tool_wrappers/python

Install On This Mac

Quick start (uvx, from PyPI)

With uv installed:

uvx apple-tools-mcp

No clone, no venv management.

From a clone

git clone https://github.com/JonathanRReed/Apple-MCPs.git

cd Apple-MCPs uv sync --all-packages

This builds one uv workspace environment with the unified entrypoint at .venv/bin/apple-tools-mcp plus every standalone server's console script (bash scripts/install_all.sh does the same, with a venv fallback for machines without uv). You can also point an MCP client at Apple-Tools-MCP/start.sh, which prefers uv run and falls back to a plain venv bootstrap (Python 3.11+ required).

Install In AI Agents

Generic MCP client config

{

"mcpServers": { "apple-tools": { "command": "uvx", "args": ["apple-tools-mcp"], "env": { "APPLE_MAIL_MCP_SAFETY_PROFILE": "safe_manage", "APPLE_CALENDAR_MCP_SAFETY_MODE": "safe_manage", "APPLE_REMINDERS_MCP_SAFETY_MODE": "safe_manage", "APPLE_FILES_MCP_ALLOWED_ROOTS": "/Users/you/Desktop,/Users/you/Documents,/Users/you/Downloads,/Users/you/Library/Mobile Documents/com~apple~CloudDocs", "APPLE_FILES_MCP_SAFETY_MODE": "safe_manage", "APPLE_SYSTEM_MCP_SAFETY_MODE": "safe_manage", "APPLE_CONTACTS_MCP_SAFETY_MODE": "safe_manage", "APPLE_NOTES_MCP_SAFETY_MODE": "full_access", "APPLE_MESSAGES_MCP_SAFETY_MODE": "full_access", "APPLE_SHORTCUTS_MCP_SAFETY_MODE": "full_access" } } } }

These values are the defaults for uvx and pip installs, so you only need the lines you want to change. With these values, replies and forwards are saved as drafts for you to send. To let the assistant send email itself, set APPLE_MAIL_MCP_SAFETY_PROFILE to full_access. The Claude Desktop bundle defaults Mail to full_access, as earlier bundles did; change it under Settings > Extensions > Apple Tools > Configure. Restart the client after changing env.

Running from a clone instead? Use /path/to/Apple-MCPs/Apple-Tools-MCP/start.sh as the command with empty args.

Claude Code example

claude mcp add --transport stdio --scope user apple-tools -- uvx apple-tools-mcp

--scope user makes the server available in every project. To share it with one repository through its .mcp.json instead, use --scope project.

What It Exposes

• Health and overview tools across all apps
• Cross-app prompts
• Delegated tools from Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System, and Maps
• Suggestions and permission guides
• Files, System, and Maps resources and prompts
• Unified wrappers for Focus, system context, Finder reveal, file open, and file tagging
• Preference tools: get, detect, and update defaults and contact preferences
• Communication tools: prepare, send, preview
• Workflow tools: archive, create reminders and notes with defaults, preview those defaulted writes, capture follow-ups, preview follow-up capture, and summarize event collaboration
• Launch-hardening tools: strict Maps wrappers, duplicate-contact detection, digest-folder helpers, and Shortcut bridge routing
• Audit tools: list recent actions and undo
• Briefing tools: daily, weekly, and communications triage
• Prompt fallback: apple_list_prompts and apple_get_prompt
• Mail thread tools: get, reply, archive
• Contacts mutation: create, update, delete with labeled methods
• Calendar and Messages permission diagnostics
• Contacts names on Messages: participants and senders carry display_name / contact_id when Contacts access is already granted, and every Messages response says why names are missing in contact_names_status (ok, permission_denied, unavailable). Only exact owners are named; a number in a different area code never borrows a contact's name.
• Launch and recovery: apple_health, apple_permission_guide, apple_recheck_permissions

Assistant Defaults

Apple-Tools-MCP can persist a lightweight assistant state file with defaults for:

• default mail account
• default archive mailbox
• default calendar
• default reminders list
• default notes folder
• preferred communication channel, messages, mail, or auto
• preferred message target type, phone, email, or auto
• per-contact preferred channel and target overrides for specific people

apple_detect_defaults() returns saved preferences with probe_status: "not_probed" and does not write the state file. To discover and persist missing targets, call apple_detect_defaults(probe_apps=true) after the user requests that discovery. This explicit probe may open Mail or Notes and request macOS permissions. The tool advertises that it can write preferences. Use apple_get_preferences to inspect defaults and apple_update_preferences to set them directly.

apple_health, apple_recheck_permissions, apple_overview, and apple://overview do not send Apple Events to apps or request new permissions. Overview keeps its resource keys but returns ok: false and status: "not_probed" for permission-sensitive app data. Read the named domain resource or tool when the user requests that data. Recent-file scans are also deferred because protected folders can require permission. Shortcuts library enumeration is also deferred. Its explicit shortcuts://all resource can run several CLI commands with a default 300-second timeout per command. Maps availability metadata remains included. Explicit app operations retain their permission checks and may launch the requested app.

When a reminder or note operation needs a missing destination, it discovers defaults only for that domain.

By default the state file is stored at ~/.apple-tools-mcp/preferences.json. Override it with APPLE_AGENT_MCP_STATE_FILE.

Apple-Tools-MCP also stores recent assistant actions in ~/.apple-tools-mcp/actions.json so the unified server can expose audit history and undo for reversible operations.

Archive, reminder, note, and Mail follow-up previews leave saved preferences and action history unchanged, including when defaults must be discovered or a destination cannot be resolved. An explicit reminder-list or notes-folder ID uses its saved label only when it matches the default; other IDs appear directly in the preview.

Archive discovery stays within the selected account. An explicit account override does not reuse another account's saved archive mailbox or replace saved defaults. If that account has no discoverable archive, pass its mailbox explicitly.

How to Work With It

• Resolve people through Contacts first, then decide between Messages or Mail based on saved defaults.
• Set per-contact preferences for people who always prefer a specific channel.
• Preview risky actions and defaulted create flows when the client wants confirmation.
• Use Mail thread helpers when the user refers to a conversation, not a single message.
• Set defaults early (archive mailbox, calendar, reminders list, notes folder) so the assistant doesn't keep asking.
• Keep contact info current so communication routing works reliably.
• Use Files before Mail, Messages, Notes, or Shortcuts when the request involves local documents.
• Check System context before interruptive actions, especially when the frontmost app, clipboard, or battery state matters.
• Treat Focus support as truthful best-effort. Use it when available, and do not invent a current Focus mode if the MCP reports unsupported on the local setup.
• Use apple_update_system_setting for macOS preference changes and apple_control_frontmost_app only when a native app-domain tool cannot complete the task.
• Prefer explicit System settings tools over generic GUI automation when the request is really a macOS preference change.
• Use GUI fallback tools only when the native domain MCP cannot complete the task and the client has granted Accessibility access. Name the target app with application or bundle_id; it must be listed in APPLE_SYSTEM_MCP_GUI_ALLOWED_APPS (see GUI input).
• Use native Maps MCP tools for maps search and directions. Do not substitute shell, web, or external map providers when validating supported Maps behavior.
• Use Shortcuts as the explicit bridge when native domain support is missing, rather than ad hoc shell or GUI work.
• Use the dedicated digest folder helpers before saving daily or weekly briefings into Notes.
• Use Maps when routing or travel time affects scheduling or communication.
• Use apple_list_recent_actions and apple_undo_action for reversible operations.
• When Mail must use a specific sender identity, pass the exact sender email in from_account, not just an account nickname.

macOS Permissions

• Mail needs Automation access to Mail
• Calendar needs Calendar access
• Reminders needs Reminders access
• Messages needs Automation access to Messages, plus Full Disk Access for history and reliable file sending
• Contacts needs Contacts access
• Contacts names on Messages responses need an explicit Contacts tool to run first (it builds the Contacts helper and asks for access); Messages reads never build the helper or ask for access, they report contact_names_status instead
• Notes needs Automation access to Notes
• Shortcuts usually works without a separate privacy prompt; it writes run output only inside APPLE_FILES_MCP_ALLOWED_ROOTS unless `APPLE_SHORTCUTS_MCP_ALL