Apple MCP

Model Context Protocol server for Apple iCloud. Gives your AI agents access to your Calendar, Reminders, and Mail — filtered through a scope engine so they only see what you want them to see.

Supports stdio and HTTP transport. Works anywhere, not just macOS. 37 tools, zero stubs.

What It Does

Connects your AI tools (Claude Desktop, Continue.dev, Cursor, or any MCP client) to your iCloud account. Three services, each independently toggleable:

• Calendar (12 tools) — list, create, update, delete events and calendars. Search by keyword, check availability, recurrence support.
• Reminders (15 tools) — full CRUD. Alarms, hashtags, URL attachments, recurrence rules, sync cursors.
• Mail (10 tools) — multi-account IMAP. Search, read, send, reply, move, flag, delete emails.

All access is gated through a scope engine. Configure which calendars, reminder lists, mail folders, and mail accounts are visible. Put a service in read-only mode if you only want your agent to see data, not change it.

Quick Start

Generate an App-Specific Password

You need an app-specific password, not your main Apple Account password.

1. Go to account.apple.com
2. Sign in → Sign-In and Security → App-Specific Passwords
3. Click "Generate an app-specific password"
4. Name it "Apple MCP" so you know what it's for
5. Copy the password (format: xxxx-xxxx-xxxx-xxxx)

You can revoke this password at any time from the same page.

Run with Docker

docker run -p 8080:8080 \
  -e APPLE_ID=you@icloud.com \
  -e APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx \
  ghcr.io/thetaroot/apple-mcp:latest

Run with pip

pip install apple-mcp
apple-mcp --transport http

Or stdio transport for local MCP clients:

apple-mcp --transport stdio

Using with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "apple": {
      "command": "python",
      "args": ["-m", "apple_mcp", "--transport", "stdio"],
      "env": {
        "APPLE_ID": "you@icloud.com",
        "APPLE_APP_SPECIFIC_PASSWORD": "xxxx-xxxx-xxxx-xxxx",
        "APPLE_CALENDAR_NAMES": "Work",
        "APPLE_REMINDER_LISTS": "Work Tasks",
        "APPLE_MAIL_MODE": "read_only"
      }
    }
  }
}

Using with Cursor or Continue.dev

Point your MCP client to the HTTP endpoint:

{
  "mcpServers": {
    "apple": {
      "url": "http://localhost:8080/mcp",
      "headers": {}
    }
  }
}

The HTTP transport uses the standard MCP Streamable HTTP protocol (spec 2025-03-26).

Configuration

All configuration via environment variables.

Authentication (required)

Variable	Description
APPLE_ID	Your iCloud email address
APPLE_APP_SPECIFIC_PASSWORD	App-specific password (shared for all services)

For better security, use per-service passwords instead:

Variable	Description
APPLE_CALENDAR_PASSWORD	Password for calendar only
APPLE_REMINDERS_PASSWORD	Password for reminders only
APPLE_MAIL_PASSWORD	Password for mail only

Service Toggles

Variable	Default	Description
APPLE_ENABLE_CALENDAR	true	Enable calendar tools
APPLE_ENABLE_REMINDERS	true	Enable reminder tools
APPLE_ENABLE_MAIL	true	Enable mail tools

Calendar Scope

Variable	Description
APPLE_CALENDAR_NAMES	Comma-separated calendar names to allow
APPLE_CALENDAR_EXCLUDE	Comma-separated calendar names to block
APPLE_CALENDAR_MODE	read_write (default) or read_only

Reminder Scope

Variable	Description
APPLE_REMINDER_LISTS	Comma-separated list names to allow
APPLE_REMINDER_EXCLUDE	Comma-separated list names to block
APPLE_REMINDER_MODE	read_write or read_only

Mail Scope

Variable	Description
APPLE_MAIL_FOLDERS	Comma-separated folder names to allow
APPLE_MAIL_EXCLUDE_FOLDERS	Comma-separated folder names to block
APPLE_MAIL_MODE	read_write or read_only

External Mail Accounts

APPLE_MAIL_ACCOUNTS='[
  {"type": "icloud", "email": "you@icloud.com", "folders_allow": ["INBOX", "Sent"]},
  {"type": "external", "email": "luis@company.com", "imap_host": "mail.company.com",
   "imap_port": 993, "smtp_host": "mail.company.com", "smtp_port": 587,
   "password_env": "MAIL_PWD_WORK", "folders_allow": ["INBOX", "Sent"]}
]'
MAIL_PWD_WORK=your-external-mail-password

Tools Reference

Calendar — 12 tools

All functional, no stubs. Recurrence support via recurrence parameter (RRULE string). Change tracking via get_changes (ctag-based).

Reminders — 15 tools

All functional, no stubs. Recurrence support: create, list, and delete recurrence rules. Sync cursor support via get_changes.

Mail — 10 tools

All functional, no stubs. Reply support via SMTP with In-Reply-To headers. Full HTML body returned by get.

Health Check

curl http://localhost:8080/health
# {"status":"ok","version":"1.1.0","tools_registered":37}

Requirements

• Python 3.12 or later
• An Apple Account with two-factor authentication enabled
• An app-specific password (generated at account.apple.com)

License

MIT