Apple-MCPs

Apple-native MCP servers for macOS — turn any AI agent into what Siri should have been.

This repository provides direct, local access to core Apple apps through the Model Context Protocol (MCP). Your AI assistant can use structured tools to work with your data — create reminders, send messages, check calendars, search mail, manage files, get directions — while everything stays in the native apps you already use.

MCP provides three primitives for working with Apple apps:

• Tools — actions like creating a reminder or sending a message
• Resources — read-only snapshots like recent notes or today's reminders
• Prompts — reusable workflows for common tasks like planning your day

Everything happens on your Mac. Your data stays in Apple's apps where it belongs.

Project Docs

• CHANGELOG.md
• CONTRIBUTING.md
• SECURITY.md
• Code Mode
• NOTICE.md

Launch Docs

• Golden Workflows
• Failure Modes
• Compatibility and Version Pinning
• Demo Script
• Checklist Template Prompt
• Per-Server E2E Checklist

Servers

• Apple-Tools-MCP, recommended. One unified server for Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System, and Maps.
• Apple Files MCP, for safe file, Finder-adjacent, and iCloud Drive workflows inside allowed roots.
• Apple System MCP, for frontmost app, battery, clipboard, truthful Focus support metadata, app-launch context, assistant-relevant macOS settings reads and writes, and bounded GUI fallback automation.
• Apple Maps MCP, for place search, travel estimates, and Apple Maps links.
• Apple Mail MCP, for Mail-only workflows.
• Apple Calendar, for Calendar-only workflows.
• Apple Reminders MCP, for task and reminder workflows.
• Apple Messages MCP, for iMessage and Messages workflows.
• Apple Contacts MCP, for contacts and recipient-resolution workflows.
• Apple Notes MCP, for notes and knowledge workflows.
• Apple Shortcuts MCP, for running Apple Shortcuts from agents.

Which One To Use

Apple-Tools-MCP (recommended) — One server that covers everything: Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System, and Maps. Includes extras like saved defaults, per-contact routing preferences, thread-aware Mail helpers, undo support, truthful Focus context, Finder-aware file workflows, and iCloud Drive awareness.

Standalone servers — Pick one if you want tighter boundaries or simpler permissions:

• Apple Files MCP, Apple System MCP, Apple Maps MCP for focused workflows
• Apple Mail MCP, Apple Calendar, Apple Reminders MCP, Apple Messages MCP, Apple Contacts MCP, Apple Notes MCP, Apple Shortcuts MCP for single-app access

Agent Routing

Some tips for working with these servers:

• tools/list is intentionally minimal. Use search_tools to discover tools, then get_tool_info to load full schemas and examples only when needed.
• Always run Contacts first when messaging a person, then choose Messages or Mail.
• Use Mail thread helpers when the user mentions a conversation.
• Reminders are for due items, Notes for reference material, Calendar for scheduled time.
• When Mail must send from a specific identity, pass the exact sender email in from_account.
• Code-mode clients can use the generated wrapper surface in generated/tool_wrappers/python instead of loading every tool schema into model context.
• See the standalone READMEs for app-specific details.

Search-First Discovery

The published Apple MCP servers are optimized for search-aware clients:

• tools/list exposes only a compact always-on surface, such as health checks, permission guidance, prompt fallbacks, search_tools, and get_tool_info
• search_tools finds deferred tools by name, description, aliases, and domain tags
• get_tool_info loads the full schema and examples for one deferred tool only when the client needs it
• direct call_tool still works for deferred tools, even if they were not included in the initial tools/list

This keeps the default context smaller while preserving the full tool surface.

Code-Mode Wrappers

The repo also ships generated artifacts for code-execution clients:

• generated/tool_catalogs, exported searchable tool metadata per server
• generated/tool_wrappers/python, generated Python wrappers for deferred tool calls

Use these when you want Anthropic-style code-mode discovery and execution without loading the entire MCP surface into the model context window.

See docs/code-mode.md for the wrapper layout, client interface, result parsing, and recommended workflow.

Install On This Mac

Recommended, install the all-in-one server

cd /path/to/Apple-MCPs/Apple-Tools-MCP
./start.sh

start.sh bootstraps and repairs the local virtual environment as needed, reinstalls when requirements.txt changes, and starts the MCP server over stdio.

Install every package into one shared environment

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

This creates a shared virtual environment and installs every standalone package plus Apple-Tools-MCP into it. Use this when you want one environment that can run any server without relying on sibling source-path imports. The installed entrypoints land in .venv/bin, for example .venv/bin/apple-tools-mcp.

Install one standalone server instead

Example:

cd /path/to/Apple-MCPs/AppleMessages-MCP
./start.sh

Every server folder follows the same pattern:

• manifest.json
• start.sh
• server.py
• README.md
• src/
• tests/

Install In AI Agents

Generic MCP client, stdio config

Most MCP clients that support local stdio servers can point directly at a server start.sh.

Example for the all-in-one server:

{
  "mcpServers": {
    "apple-tools": {
      "command": "/path/to/Apple-MCPs/Apple-Tools-MCP/start.sh",
      "args": [],
      "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"
      }
    }
  }
}

For launch-quality assistant behavior, use the assistant-grade safety settings shown in Apple-Tools-MCP/README.md instead of an empty env block.

Example for a standalone server:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "/path/to/Apple-MCPs/AppleReminders-MCP/start.sh",
      "args": [],
      "env": {
        "APPLE_REMINDERS_MCP_SAFETY_MODE": "safe_manage"
      }
    }
  }
}

Claude Code example

Add the all-in-one server:

claude mcp add --transport stdio --scope project \
  apple-tools \
  -- /path/to/Apple-MCPs/Apple-Tools-MCP/start.sh

Add a standalone server:

claude mcp add --transport stdio --scope project \
  apple-notes \
  -- /path/to/Apple-MCPs/AppleNotes-MCP/start.sh

Launch Checklist

• Start the server: ./start.sh
• Add the start.sh path to your MCP client
• Reconnect the client so the server loads
• Call the health tool to verify it's working
• If permissions fail, call the permission guide tool
• After fixing permissions, call the recheck tool (or shortcuts_refresh_state for Shortcuts)
• Do not treat shell, curl, UI scraping, or external APIs as a passing result when the suite claims native MCP support for that capability
• For Maps, a pass requires native Apple Maps MCP success
• For Focus and notifications, a pass requires truthful MCP output. Do not invent active Focus state or Notification Center history that the suite does not actually expose.

Protocol Verification

Use stdio for normal local agent setups. Apple-Tools-MCP also supports streamable-http for protocol validation and hosted clients.

Run the full official active server conformance suite against Apple-Tools-MCP:

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

In another shell:

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

Run lightweight Inspector smoke checks across all published servers:

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

The repository also includes GitHub Actions for both checks in protocol-ci.yml.

Health And Recovery Tools

Server	Health tool	Permission or recovery tools
Apple-Tools-MCP	apple_health	apple_permission_guide, apple_recheck_permissions
Apple Mail MCP	mail_health	mail_permission_guide, mail_recheck_permissions
Apple Calendar	calendar_health	calendar_permission_guide, calendar_recheck_permissions
Apple Reminders MCP	reminders_health	reminders_permission_guide, reminders_recheck_permissions
Apple Messages MCP	messages_health	messages_permission_guide, messages_recheck_permissions
Apple Contacts MCP	contacts_health	contacts_permission_guide, contacts_recheck_permissions
Apple Notes MCP	notes_health	notes_permission_guide, notes_recheck_permissions
Apple Shortcuts MCP	shortcuts_health	shortcuts_permission_guide, shortcuts_refresh_state
Apple Files MCP	files_health	files_permission_guide
Apple System MCP	system_health	system_permission_guide
Apple Maps MCP	maps_health	maps_permission_guide

macOS Permissions

Different Apple apps require different permissions:

Server	What macOS may ask for
Apple Mail	Automation access to Mail
Apple Calendar	Calendar access
Apple Reminders	Reminders access
Apple Messages	Automation access to Messages, plus Full Disk Access for history
Apple Contacts	Contacts access
Apple Notes	Automation access to Notes
Apple Shortcuts	Usually no separate privacy prompt
Apple Files	No privacy prompt, access is limited by the configured allowed roots
Apple System	Some actions may trigger System Events, Accessibility, or automation prompts
Apple Maps	No privacy prompt, but local Swift helper compilation needs Xcode command line tools

Repo Layout

• Apple-Tools-MCP/, unified server
• AppleFiles-MCP/, Files
• AppleSystem-MCP/, System
• AppleMaps-MCP/, Maps
• AppleContacts-MCP/, Contacts
• AppleMail-MCP/, Mail
• Apple-Calendar-MCP/, Calendar
• AppleReminders-MCP/, Reminders
• AppleMessages-MCP/, Messages
• AppleNotes-MCP/, Notes
• AppleShortcuts-MCP/, Shortcuts
• SharedAppleBridge/, shared native bridge code used by EventKit-backed servers
• .build/, local helper build output

Notes

• This suite is for macOS.
• Apple Messages history access still needs Full Disk Access.
• The unified server folder is Apple-Tools-MCP.
• The calendar server folder is Apple-Calendar-MCP.
• Apple Files access is limited to the roots in APPLE_FILES_MCP_ALLOWED_ROOTS.
• Apple System write actions can be scoped down with APPLE_SYSTEM_MCP_SAFETY_MODE.
• Apple Maps depends on a local Swift helper and Xcode command line tools for search and directions.
• Apple-Tools-MCP can persist assistant defaults in ~/.apple-tools-mcp/preferences.json, or the path from APPLE_AGENT_MCP_STATE_FILE.
• Apple-Tools-MCP also stores recent assistant actions in ~/.apple-tools-mcp/actions.json for audit and undo workflows.
• Apple-Tools-MCP now aggregates Files, System, and Maps alongside the app-specific Apple servers.
• APPLE_AGENT_MCP_CONFORMANCE_MODE=1 is for protocol validation only. It adds the official MCP conformance fixtures on Apple-Tools-MCP and switches HTTP mode to full streaming behavior.
• Apple-Tools-MCP now includes task-capable briefing tools, apple_generate_daily_briefing, apple_generate_weekly_briefing, and apple_triage_communications_task.
• Apple-Tools-MCP also includes prompt fallback tools, apple_list_prompts and apple_get_prompt, for tool-only MCP clients.
• The standalone servers now expose prompt fallback tools and explicit resource subscribe or unsubscribe handlers, so prompt-heavy workflows degrade more cleanly in thinner MCP clients.
• Apple Mail now includes thread helpers, mail_get_thread, mail_reply_latest_in_thread, and mail_archive_thread.
• Apple Contacts can now create, update, and delete contacts with labeled phone numbers and email addresses.
• Mail search requires a query string. Use a sender, a subject fragment, or * as a wildcard.
• Reminders due_date requires a timezone offset like yyyy-MM-ddTHH:mm:ss-HH:00.
• service_name should be omitted on iMessage sends.