Apple Messages

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.

Everything happens on your Mac over local stdio. Your data stays in Apple's apps where it belongs. Free and open source under the MIT License.

Built on MCP specification 2026-07-28 (Python SDK 2.x) with backward compatibility for clients speaking older protocol revisions.

Servers

• Apple-Tools-MCP, recommended. One unified server for Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System, and Maps — plus saved defaults, per-contact routing preferences, thread-aware Mail helpers, undo support, briefing tools, and cross-app workflows.
• Standalone servers when you want tighter boundaries or simpler permissions: Mail · Calendar · Reminders · Messages · Contacts · Notes · Shortcuts · Files · System · Maps

Install

Run from PyPI (uvx)

Once you have uv installed, every server runs with a one-liner — no clone, no venv management:

uvx apple-tools-mcp

Standalone servers work the same way (uvx apple-mcp-mail, uvx apple-calendar-mcp, ...).

Claude Code

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

Generic MCP client (stdio JSON config)

{
  "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"
      }
    }
  }
}

See Apple-Tools-MCP/README.md for the assistant-grade safety settings recommended for daily use.

Claude Desktop (one-click bundle)

Download the .mcpb bundle for a server from Releases and double-click it — Claude Desktop installs and manages it, including configuration.

From a clone

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

That builds one workspace environment with every server's entry point in .venv/bin (for example .venv/bin/apple-tools-mcp). Each server folder also has a start.sh that MCP clients can point at directly — it prefers uv and falls back to a plain venv bootstrap.

macOS Permissions

Different Apple apps require different permissions. Each server ships a health tool, a permission guide tool, and a recheck tool, so your agent can diagnose and fix permission problems by itself.

Server	What macOS may ask for	Health tool	Recovery tools
Apple-Tools-MCP	Everything below, as used	apple_health	apple_permission_guide, apple_recheck_permissions
Mail	Automation access to Mail	mail_health	mail_permission_guide, mail_recheck_permissions
Calendar	Calendar access	calendar_health	calendar_permission_guide, calendar_recheck_permissions
Reminders	Reminders access	reminders_health	reminders_permission_guide, reminders_recheck_permissions
Messages	Automation access to Messages, plus Full Disk Access for history	messages_health	messages_permission_guide, messages_recheck_permissions
Contacts	Contacts access	contacts_health	contacts_permission_guide, contacts_recheck_permissions
Notes	Automation access to Notes	notes_health	notes_permission_guide, notes_recheck_permissions
Shortcuts	Usually no separate privacy prompt	shortcuts_health	shortcuts_permission_guide, shortcuts_refresh_state
Files	No privacy prompt; access limited to configured allowed roots	files_health	files_permission_guide
System	System Events, Accessibility, or automation prompts for some actions	system_health	system_permission_guide
Maps	No privacy prompt; local Swift helper needs Xcode command line tools	maps_health	maps_permission_guide

Tool Discovery

Servers expose their full tool surface through tools/list (with readOnlyHint/destructiveHint annotations and structured output schemas), which is what modern deferred-loading clients expect. For context-constrained clients, every server also ships two helper tools:

• search_tools — ranked keyword/alias search over the server's tool catalog
• get_tool_info — full schema, metadata, and example calls for one tool

Agent Routing

Some tips for working with these servers:

• Always run Contacts first when messaging a person, then choose Messages or Mail.
• Use Mail thread helpers (mail_get_thread, mail_reply_latest_in_thread, mail_archive_thread) 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.
• Mail search requires a query string: a sender, a subject fragment, or * as a wildcard.
• Reminders due_date requires a timezone offset like yyyy-MM-ddTHH:mm:ss-08:00.
• Omit service_name on iMessage sends.
• Apple-Tools-MCP includes briefing tools: apple_generate_daily_briefing, apple_generate_weekly_briefing, and apple_triage_communications_task.
• Prompt-fallback tools (apple_list_prompts, apple_get_prompt, and per-server equivalents) cover clients that only support tools.

Code-Mode Wrappers

For code-execution clients, the repo ships generated artifacts so agents can call tools as Python functions without loading every schema into context:

• generated/tool_catalogs/ — searchable tool metadata per server
• generated/tool_wrappers/python/ — generated Python wrappers for every tool

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

Transports and Protocol Verification

stdio is the default and recommended transport for local use. Every server also supports streamable-http via env vars (APPLE_<DOMAIN>_MCP_TRANSPORT=streamable-http, plus _HOST/_PORT).

Run the official MCP conformance suite against Apple-Tools-MCP:

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

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

Lightweight Inspector smoke checks across all servers:

bash scripts/inspector_smoke.sh

CI runs lint, the full test suite (macOS and Linux), generated-artifact drift checks, Inspector smoke checks, and the conformance suite — see .github/workflows.

Repo Layout

• Apple-Tools-MCP/ — unified server (module apple_agent_mcp, env prefix APPLE_AGENT_MCP_*)
• Apple<Domain>-MCP/ — standalone servers (Apple-Calendar-MCP is the calendar server)
• AppleMCPCommon/ — shared discovery/search helpers (apple-mcp-common on PyPI)
• generated/ — code-mode catalogs and wrappers (regenerated by CI checks)
• scripts/ — install, smoke-check, artifact-generation, and bundle-build helpers
• docs/ — project and launch docs

The repository is a uv workspace: pyproject.toml at the root defines members, and uv.lock pins the whole dependency graph.

Project Docs

• CHANGELOG.md
• CONTRIBUTING.md
• SECURITY.md
• Code Mode
• Publishing
• NOTICE.md — trademark notice
• Launch docs — golden workflows, failure modes, compatibility, demo script

Notes

• This suite is for macOS. Apple Messages history access needs Full Disk Access.
• 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 compiled with Xcode command line tools.
• Apple-Tools-MCP persists assistant defaults in ~/.apple-tools-mcp/preferences.json (or APPLE_AGENT_MCP_STATE_FILE) and recent assistant actions in ~/.apple-tools-mcp/actions.json for audit and undo workflows.
• APPLE_AGENT_MCP_CONFORMANCE_MODE=1 is for protocol validation only; it registers the official conformance fixtures.