Skip to content

Releases

v0.3.0 — Photos integration

Choose a tag to compare

@gheydon gheydon released this 09 Jun 01:34

apple-mcp v0.3.0

Adds Photos integration — four new tools built on PhotoKit.

New tools

Tool What it does
photos_list_albums Lists user-created albums and non-empty smart albums (Favorites, Screenshots, Selfies, Slo-mo, etc.)
photos_search Filter assets by date range, favorites-only, media type (image/video/audio), and/or album. Returns metadata (date, dimensions, location, duration, media subtypes).
photos_export Writes the full-resolution original of a photo or video to a path on disk. Uses PHImageManager for stills and PHAssetResourceManager for video originals.
photos_view Returns a downsized JPEG thumbnail as inline image content so the agent can actually see the photo. max_dimension defaults to 512 px.

Permissions

First Photos call triggers the standard macOS prompt at System Settings → Privacy & Security → Photos. The server accepts both Full Access and Limited Access.

Total tool inventory: 17

Calendar (3) · Reminders (4) · Contacts (2) · Photos (4) · Messages (4)

Install / upgrade

brew upgrade apple-mcp

Or from the tarball:

tar -xzf apple-mcp-0.3.0-macos.tar.gz
./apple-mcp register

Artefact

apple-mcp-0.3.0-macos.tar.gz — universal arm64 + x86_64, signed with Developer ID Application and notarized.

  • Tarball sha256: 59df2ad6136c92b17ca92c0615035f97b5e5080913bad18c9d4f8217cea01e0c
  • Binary sha256: e36b6368f6943c0c7b175e908669ab98ff657abddb510023eb9100fb3c993eb1

v0.2.0 — register/unregister

Choose a tag to compare

@gheydon gheydon released this 27 May 01:07

apple-mcp v0.2.0

Adds register / unregister subcommands so you no longer have to hand-edit MCP host JSON configs.

New commands

apple-mcp register      # interactively wires apple-mcp into detected hosts
apple-mcp unregister    # removes the entry again
apple-mcp version
apple-mcp help

What register does:

  • Detects which MCP hosts you have installed by checking for these config files:
    • ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop)
    • ~/.claude.json (Claude Code)
  • Prints the current state per host (registered / not registered, current command path)
  • Asks for confirmation per host (skip with --yes)
  • Adds an apple entry under mcpServers, preserving any other servers already there
  • Backs up the pristine pre-modification config to <config>.bak; subsequent runs save timestamped backups so the original is never clobbered

Flags:

  • --host claude-desktop or --host claude-code — target one host
  • --yes / -y — non-interactive
  • --path <path> — register a specific binary location (defaults to the running binary)

Download

apple-mcp-0.2.0-macos.tar.gz — universal arm64+x86_64 binary, signed with Developer ID Application and notarized by Apple.

Install / upgrade

brew upgrade apple-mcp

(once the Homebrew tap formula is bumped — happens automatically via GitHub Actions when the tap PAT is configured).

Or from the tarball:

tar -xzf apple-mcp-0.2.0-macos.tar.gz
./apple-mcp register

Tools

Unchanged — 13 tools across Calendar, Reminders, Contacts, and Messages. See README.

macOS permissions

First time each tool group is used, macOS prompts:

  • Calendar / Reminders / Contacts — Privacy & Security → Calendar / Reminders / Contacts
  • Messages send — Privacy & Security → Automation → Messages
  • Messages read — host process needs Full Disk Access to read ~/Library/Messages/chat.db

v0.1.1 — Notarized release

Choose a tag to compare

@gheydon gheydon released this 27 May 00:49

apple-mcp v0.1.1

Notarized release. Universal arm64 + x86_64 macOS binary, signed with a Developer ID Application certificate and notarized by Apple — no Gatekeeper warnings, no xattr workaround.

Download

apple-mcp-0.1.1-macos.tar.gz contains:

  • apple-mcp — universal Mach-O binary (arm64 + x86_64), signed and notarized
  • LICENSE, README.md
tar -xzf apple-mcp-0.1.1-macos.tar.gz
./apple-mcp   # runs as a stdio MCP server; wire into your MCP host's config

Tools (13 total)

Calendar — calendar_list_calendars, calendar_list_events, calendar_create_event
Reminders — reminders_list_lists, reminders_list, reminders_create, reminders_complete
Contacts — contacts_search (name/phone/email, includes addresses, birthdays, URLs), contacts_create
Messages — messages_list_chats, messages_recent, messages_search, messages_send

Wiring into an MCP host

Claude Desktop / similar — add to your MCP servers config:

{
  "mcpServers": {
    "apple": {
      "command": "/absolute/path/to/apple-mcp"
    }
  }
}

macOS permissions

First time each set of tools is used, macOS prompts for the relevant access:

  • Calendar — Privacy & Security → Calendar
  • Reminders — Privacy & Security → Reminders
  • Contacts — Privacy & Security → Contacts
  • Messages send — Privacy & Security → Automation → Messages
  • Messages read — requires Full Disk Access for the host process so ~/Library/Messages/chat.db is readable

Changes since v0.1.0

  • Binary is now signed with a Developer ID Application certificate (Heydon Enterprises Pty Ltd, team DF23J8A7QQ) and successfully notarized
  • scripts/release.sh updated to handle notarization via NOTARY_PROFILE env var
  • Server version string bumped to 0.1.1

v0.1.0 — Initial release

Choose a tag to compare

@gheydon gheydon released this 27 May 00:18

apple-mcp v0.1.0

First public release. A Swift-native Model Context Protocol server exposing macOS Calendar, Reminders, Contacts, and Messages to AI agents.

Tools

Calendar — calendar_list_calendars, calendar_list_events, calendar_create_event
Reminders — reminders_list_lists, reminders_list, reminders_create, reminders_complete
Contacts — contacts_search (name/phone/email), contacts_create
Messages — messages_list_chats, messages_recent, messages_search, messages_send

Download

apple-mcp-0.1.0-macos.tar.gz contains:

  • apple-mcp — universal Mach-O binary (arm64 + x86_64), signed with an Apple Development certificate
  • LICENSE, README.md
tar -xzf apple-mcp-0.1.0-macos.tar.gz
./apple-mcp --help   # or wire it into your MCP client's config

Gatekeeper note

The binary is signed with an Apple Development certificate, not a Developer ID + notarization. On first launch macOS may say "developer cannot be verified". To allow it:

xattr -d com.apple.quarantine apple-mcp

Or right-click → Open the first time and approve in System Settings → Privacy & Security.

macOS permissions

First time each set of tools is used, macOS will prompt for the relevant access:

  • Calendar — Privacy & Security → Calendar
  • Reminders — Privacy & Security → Reminders
  • Contacts — Privacy & Security → Contacts
  • Messages send — Privacy & Security → Automation → Messages
  • Messages read — requires Full Disk Access for the host process (Terminal, Claude Desktop, etc.) so ~/Library/Messages/chat.db is readable

Wiring into an MCP host

For Claude Desktop or similar, add to the MCP servers config:

{
  "mcpServers": {
    "apple": {
      "command": "/absolute/path/to/apple-mcp"
    }
  }
}

Source build

git clone https://github.com/gheydon/apple-mcp.git
cd apple-mcp
swift build -c release

Requires Swift 6.0+ (Xcode 16+) on macOS 14+.