Fruit Forwarder MCP server
Commit Sep 8, 2026Provides local macOS access to Apple Reminders and read-only Calendar data via EventKit for AI clients and Home Assistant.
Also known as pdfowler/fruit-forwarder, fruit-forwarder
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Sep 8, 2026
- License
- MIT
What is Fruit Forwarder MCP?
Fruit Forwarder provides local macOS access to Apple Reminders and read-only Calendar data via EventKit for AI clients and Home Assistant.
Summary generated from the project's README
About Fruit Forwarder MCP server
Fruit Forwarder MCP acts as a local bridge for macOS users to connect Apple Reminders and read-only Calendar data to AI clients and Home Assistant. It utilizes a native Swift helper to interact with Apple's EventKit API, ensuring that all Apple credentials remain on the local machine. The system operates as a stdio MCP server and uses a LaunchAgent to manage the background process on your Mac.
Developers can configure specific reminder lists through an allowlist in a JSON configuration file. The server supports creating, editing, completing, and reopening items, though it intentionally excludes deletion and list management to maintain security boundaries. For Home Assistant integration, the bridge pushes data via a secure webhook using a 256-bit token stored in the macOS login Keychain. This setup allows for automated task synchronization while keeping sensitive household contents and credentials private.
What you can do with it
- 1Sync reminders to Home AssistantA developer can push specific allowlisted reminder lists to a Home Assistant instance for smart home automation.
- 2Manage tasks via AI clientsAn AI client can interact with local macOS reminders to create or complete tasks using the MCP interface.
- 3Maintain data privacyUsers can ensure their private reminder titles and notes are not exposed in logs or sent to external services.
- 4Control data retentionA developer can limit how long completed tasks stay visible in the bridge to prevent overwhelming Home Assistant.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepdfowler/fruit-forwarder is public and reachablegithub.com/pdfowler/fruit-forwarder ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-08github.com/pdfowler/fruit-forwarder ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFruit Forwarder
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.
Security boundary
- Apple credentials never leave macOS. EventKit uses the Mac user's signed-in accounts and macOS Reminders permission.
- The bridge makes outbound HTTPS requests to one Home Assistant webhook. It does not hold a Home Assistant long-lived access token.
- The webhook uses a random 256-bit path token and is registered
local_only. - Both HA and the bridge enforce a reminder-list allowlist. The bridge uses exact EventKit list IDs for reads and writes.
- HA and MCP offer create, edit, complete, and reopen. Delete and list-management operations are intentionally absent.
- MCP can expose only read tools with
"mcp_read_only": true; HA editing is independently available. - The webhook token is stored in the macOS login Keychain. It is not in the LaunchAgent environment, repository, or JSON configuration.
- Logs contain counts, command IDs, and errors—not reminder titles or notes.
Components
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.
Quick start
-
Build and install on a Mac signed in to the iCloud account that owns the lists:
./scripts/install-macos.sh --install-only -
Grant Reminders access when macOS prompts. Discover exact list IDs:
~/Library/Application\ Support/icloud-reminders-bridge/bin/icloud-reminders-bridge discover -
Edit
~/.config/icloud-reminders-bridge/config.json, adding only the lists you want to expose. Runpairto 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:
./scripts/install-macos.sh
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.
Configuration
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.
Development
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:
task check # Go, HA, metadata and script checks
task test # Go, HA, and native EventKit tests when running on macOS
task build:macos # build staged Go/native outputs on macOS
task package:ha # build the HACS tree and versioned HA archive
task package:macos # build a versioned macOS tarball on macOS
task package:mcp # build the macOS MCPB and candidate registry metadata
task install:local PACKAGE=dist/macos/fruit-forwarder-macos-0.1.0.tar.gz
task release:check # build/validate every target available on this host
task release:prepare # record the verified candidate manifest
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.
go test -race ./...
go vet ./...
The native helper requires macOS and the EventKit permission prompt. See
CONTRIBUTING.md for local build details and SECURITY.md for disclosure guidance.
Fruit Forwarder MCP questions
Does the bridge store my Apple credentials?
No, Apple credentials never leave your macOS device as the bridge uses the Mac user's signed-in accounts and macOS Reminders permission.
Can I delete reminders using this server?
No, delete and list-management operations are intentionally excluded from the available operations.
How long are completed reminders kept in the system?
Completed reminders are retained for a default of 30 days to prevent history from overwhelming Home Assistant.