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

uvx apple-tools-mcp

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

Install In AI Agents

{
  "mcpServers": {
    "apple-tools": {
      "command": "uvx",
      "args": ["apple-tools-mcp"],
      "env": {
        "APPLE_MAIL_MCP_SAFETY_PROFILE": "full_access",
        "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"
      }
    }
  }
}

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

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
• 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

Detect and persist sensible defaults with apple_detect_defaults, inspect them with apple_get_preferences, and override them with apple_update_preferences.

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.
• 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
• Contacts needs Contacts access
• Notes needs Automation access to Notes
• Shortcuts usually works without a separate privacy prompt
• Files access is controlled by APPLE_FILES_MCP_ALLOWED_ROOTS, not by a macOS privacy prompt
• System actions may trigger System Events, Accessibility, or automation prompts depending on the host app
• Focus status is best-effort and truthful on unsigned local installs
• Notification Center history is not claimed where macOS does not expose it cleanly
• Maps does not need a privacy prompt, but search and directions require the local Swift helper to compile

Launch Checklist

• Add uvx apple-tools-mcp (or a clone's Apple-Tools-MCP/start.sh / installed .venv/bin/apple-tools-mcp entrypoint) to your MCP client
• Reload or reconnect the client so the Apple-Tools-MCP tool surface is loaded into context
• Call apple_health first to verify every domain
• If a domain is blocked, call apple_permission_guide
• After changing macOS permissions, call apple_recheck_permissions

Transports and Protocol Verification

stdio is the default and recommended transport. Set APPLE_AGENT_MCP_TRANSPORT=streamable-http (with optional APPLE_AGENT_MCP_HOST and APPLE_AGENT_MCP_PORT) to serve Streamable HTTP instead — used below for protocol validation.

Official MCP conformance

Start Apple-Tools-MCP in conformance mode:

cd /path/to/Apple-MCPs/Apple-Tools-MCP
APPLE_AGENT_MCP_TRANSPORT=streamable-http \
APPLE_AGENT_MCP_PORT=8765 \
APPLE_AGENT_MCP_CONFORMANCE_MODE=1 \
./start.sh

Then run the official active suite:

npx -y @modelcontextprotocol/conformance server \
  --url http://127.0.0.1:8765/mcp \
  --suite active

APPLE_AGENT_MCP_CONFORMANCE_MODE=1 adds an opt-in MCP conformance surface covering content types, resources, resource templates, prompts, progress, and completion (fixtures for features removed by spec 2026-07-28 are intentionally absent). It is intended for CI and protocol testing, not normal assistant use.

The briefing and triage tools (apple_generate_daily_briefing, apple_generate_weekly_briefing, apple_triage_communications_task) are standard synchronous tools — the experimental MCP tasks API they previously used was removed from the spec (SEP-1686) and SDK, with the same tool names and results.

Launch Docs

• Golden Workflows
• Failure Modes
• Compatibility and Version Pinning
• Code Mode
• Demo Script
• Checklist Template Prompt

Inspector CLI smoke check

From this server directory:

npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method tools/list
npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method prompts/list
npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method resources/list

For the full repo-wide smoke pass, run:

cd /path/to/Apple-MCPs
bash scripts/inspector_smoke.sh

Agent Routing Prompt

<apple_tools>
`tools/list` returns the full tool surface. If context is constrained, use `search_tools` first, then `get_tool_info` only for the tools you plan to call.

<routing>
  <imessage trigger="text, message, msg, iMessage">
    Resolve recipient via Contacts first. Confirm if multiple matches.
    Omit service_name parameter entirely.
  </imessage>

  <contacts trigger="lookup, phone number, email, contact">
    Run before any iMessage or Mail action.
  </contacts>

  <mail trigger="email, mail, inbox, draft, reply">
    Search requires a query string (sender, subject, or "*" as wildcard). No list-all endpoint.
    If text vs. email is ambiguous, ask once.
  </mail>

  <calendar trigger="calendar, event, schedule, appointment, meeting, block time">
    Confirm date, time, duration, and title before writing.
  </calendar>

  <reminders trigger="remind me, task, to-do, don't forget">
    Reminders are organized into lists. Identify available lists on first use and set a default.
    due_date requires timezone offset: yyyy-MM-ddTHH:mm:ss-HH:00
  </reminders>

  <notes trigger="note, jot down, write this down, save this">
    Multiple accounts may have a "Notes" folder. Identify them on first use and set a default.
    Use for reference only. Time-sensitive items go to Reminders or Calendar.
  </notes>

  <shortcuts trigger="shortcut, automation, run shortcut">
    List available shortcuts before running if request is vague.
  </shortcuts>

  <files trigger="file, folder, attachment, document, download, desktop">
    Use Files before Mail, Messages, Notes, or Shortcuts when the request references local paths or attachments.
    Confirm the exact path before mutation or send actions.
  </files>

  <system trigger="clipboard, frontmost app, battery, notification, open app">
    Use System when local desktop context affects the next action.
    Keep writes scoped unless the user clearly asked for a notification, clipboard update, or app launch.
  </system>

  <maps trigger="map, directions, route, commute, eta, address, place">
    Use Maps when place lookup or travel time affects scheduling or communication.
    Confirm origin, destination, and transport mode for time-sensitive plans.
  </maps>
</routing>

<disambiguation>
  1. Has due date/time -> Reminders
  2. Reference material, no action -> Notes
  3. Involves another person -> iMessage or Mail (Contacts first)
  4. Text vs. email unclear -> ask once
</disambiguation>

<known_gotchas>
  - service_name on iMessage calls causes error (-1728). Omit it.
  - Bare timestamps without timezone offset fail on Reminders.
  - Mail has no "list recent" endpoint. Always pass a search query.
  - Use `search_tools` plus `get_tool_info` to inspect tools without loading every schema into context.
  - Multiple Notes folders exist across accounts. Pick one default.
  - Files access is limited to APPLE_FILES_MCP_ALLOWED_ROOTS.
  - Some System actions depend on host app automation approval.
  - Maps search and directions depend on the local Swift helper and Xcode command line tools.
</known_gotchas>
</apple_tools>

Related Servers

• Apple Files MCP
• Apple System MCP
• Apple Maps MCP
• Apple Mail MCP
• Apple Calendar
• Apple Reminders MCP
• Apple Messages MCP
• Apple Contacts MCP
• Apple Notes MCP
• Apple Shortcuts MCP

Mail attachments

Set APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT to a dedicated directory before attaching local files to a draft or outgoing message. Attachments are disabled when this variable is unset. The same directory restriction applies to the standalone Mail server and the unified Apple Tools server.

Select a calendar by its displayed name and source in calendar_list_calendars, then pass its returned calendar_id unchanged. Re-list calendars after changing Calendar permissions and restarting the MCP server. For full alarm edits, list events with a native calendar ID and use the returned native event ID; existing applescript:: IDs continue to use automation. See Selecting calendar and event identifiers.

Calendar alarm edits follow the standalone server contract: full editing and combined explicit-alarm/field updates require native EventKit. In the automation fallback, omit alarms for ordinary field edits. Alarm-only initial alerts and empty-list no-ops require every alert collection to be readable and empty. Failed insertion or an interrupted mutation can have an unknown outcome; inspect the event before retrying. See Calendar alarm support.