The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Fruit Forwarder MCP listing page.
A local macOS bridge between Apple Reminders/Calendar and Home Assistant. It uses Apple's EventKit API for reads and writes, exposes a small stdio MCP server, and pushes allowlisted data to Home Assistant.
Early release. Reminders and read-only calendars support HA and local MCP (see calendar setup). Background EventKit permission and reboot recovery still need validation; see the release roadmap. Start with the complete setup guide for Home Assistant and local MCP configuration. Standard Lovelace examples are in docs/dashboard-examples.md. See the compatibility matrix for the current support claim and architecture decisions for the monorepo and trust-boundary choices. For issue-reporting boundaries and redaction guidance, see SUPPORT.md. The detailed threat model and security limitations are in SECURITY.md. Third-party attribution is recorded in THIRD_PARTY_NOTICES.md. Release history is tracked in CHANGELOG.md. The release gate is tracked in docs/acceptance-evidence.md. Mutation and recovery semantics are documented in docs/command-lifecycle.md. Reminder field support and update-preservation rules are documented in docs/reminder-semantics.md. Home Assistant's diagnostics download reports only redacted operational counts and timestamps; it excludes credentials and household contents.
local_only."mcp_read_only": true; HA editing is
independently available.eventkit-helper: a small native Swift helper using only Apple's public
EventKit API.cmd/icloud-reminders-bridge: discovery, pairing, daemon, one-shot sync, and
stdio MCP entrypoint. It invokes the native helper directly with a 30-second
timeout; macOS enforces Reminders access for the responsible application.homeassistant/custom_components/icloud_reminders_bridge: push-driven HA todo
entities and the durable command queue.deployment: a user LaunchAgent for the Mac.Build and install on a Mac signed in to the iCloud account that owns the lists:
Grant Reminders access when macOS prompts. Discover exact list IDs:
Edit ~/.config/icloud-reminders-bridge/config.json, adding only the lists
you want to expose. Run pair to create a persistent bearer token and configure the
Home Assistant custom integration with that token and the same list IDs.
Start the per-user LaunchAgent:
After a reboot or upgrade, icloud-reminders-bridge doctor --json checks the
configured helper and (when HA sync is enabled) the pairing Keychain item
without reading reminder contents.
If a write reaches an uncertain EventKit outcome, doctor reports the
in-flight command and syncing pauses until it is explicitly resolved; see the
recovery steps in docs/setup.md.
If Home Assistant presents a different persisted command-queue epoch after a
restore, the bridge also pauses and requires explicit reset-queue-epoch
review before applying queued mutations.
The pairing token is stored in the macOS login Keychain. Do not commit the runtime config, state file, logs, or token.
The packaged build uses the stable reverse-DNS service identifier
com.pdfowler.fruitforwarder. Existing prototype configs that explicitly use
com.example.icloud-reminders-bridge remain valid; do not delete the old
Keychain item until the replacement installation has been verified.
completed_retention controls how long completed reminders remain in the
bridge snapshot. The default is 30 days (720h); this prevents an old iCloud
history from filling Home Assistant while preserving recent completed items.
The bridge intentionally does not expose delete or list-management operations. Review the allowlist and the Home Assistant webhook path before placing the service on a network shared with untrusted clients.
The repository is a small polyglot monorepo: Go owns the bridge/MCP process, Swift owns the EventKit helper, and the Home Assistant integration is exported as a deterministic HACS distribution. Use Task for the common cross-target commands:
The MCP registry metadata is intentionally rendered only after a versioned MCPB artifact has been built and hashed; see packaging/mcp/README.md. No publishing command is implicit in a build or release check. Maintainer publication gates and the HACS/MCP follow-up steps are documented in docs/publishing.md.
task install:local is an explicit macOS action. It verifies a packaged
archive and its checksum before extracting it into a temporary directory and
running the package installer. Add INSTALL_ONLY=true to stage binaries
without activating launchd, or MIGRATE_HOME_CTRL=true when intentionally
preparing the known legacy configuration migration.
The macOS tarball is self-installing: extract it, copy the exact IDs into the
included configuration, and run scripts/install-package-macos.sh. The source
checkout's scripts/install-macos.sh remains the developer build/install path.
The packaged installer preserves the previous executable pair under the same
rollback directory and uses the bundled LaunchAgent renderer; it does not
overwrite an existing runtime configuration or Keychain item.
The bundled scripts/uninstall-macos.sh removes only service files and keeps
that runtime data for an explicit later cleanup decision.
The native helper requires macOS and the EventKit permission prompt. See
CONTRIBUTING.md for local build details and SECURITY.md for disclosure guidance.