Frieda MCP server
Commit Nov 10, 2026Connects Apple iCloud calendars, contacts, mail, and notes to an AI client via Home Assistant.
Also known as nadeo360/friedafetch
- Stars
- 7
- Tools
- 30
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- MIT
What is Frieda MCP?
Frieda connects Apple iCloud calendars, contacts, mail, and notes to an AI client via Home Assistant. It exposes 30 tools, such as icloud_list_calendars, icloud_list_events, icloud_get_event.
Summary generated from the project's README
About Frieda MCP server
Accessing your Apple iCloud data from within an AI assistant is what friedafetch enables for Home Assistant users. This integration connects your Apple ID to your local or remote AI client by exposing calendars, contacts, email, and notes as functional tools. It works by using an app-specific password and requires an Apple ID with two-factor authentication enabled.
Users can interact with their data through various conversation agents like Claude, ChatGPT, or local models via Home Assistant's built-in MCP endpoint or the Model Context Protocol Server integration. The server supports standard protocols including CalDAV for calendars, CardDAV for contacts, and IMAP/SMTP for email. Note that iCloud notes are specifically handled through the IMAP Notes folder.
Administrators can control the level of access by enabling or disabling specific tool groups, setting read-only modes, or configuring security guard rails like recipient policies and quotas. This allows for a customized experience where an AI can search for events, manage contacts, or send emails based on your specific permission settings.
Written from the project's README. Every use case is checked against a quote from it.
Frieda MCP tools 30
Detected from the READMEicloud_list_calendarsicloud_list_eventsicloud_get_eventicloud_create_eventicloud_update_eventicloud_delete_eventicloud_search_contactsicloud_get_contacticloud_create_contacticloud_update_contacticloud_delete_contacticloud_list_mailboxes
Show all 30 toolsShow fewer tools
icloud_search_mailicloud_get_mailicloud_send_mailicloud_mark_mailicloud_move_mailicloud_delete_mailicloud_approval_statusicloud_mailbox_statsicloud_unsubscribeicloud_save_attachmentsicloud_find_free_timeicloud_upcoming_birthdaysicloud_find_duplicate_contactsicloud_list_notesicloud_get_noteicloud_create_noteicloud_update_noteicloud_delete_note
Automated checks
Ran Nov 14, 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 reachablenadeo360/friedafetch is public and reachablegithub.com/nadeo360/friedafetch ↗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-11-10github.com/nadeo360/friedafetch ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 7.3 / 10; weakest: Maintained 0, Code-Review 0, Fuzzing 0scorecard.dev/viewer/?uri=github.com/nadeo360/friedafetch ↗Pass
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model30 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFrieda – MCP connector for iCloud
Frieda (technical name friedafetch) is a Home Assistant integration (Marketplace, HACS) that connects Apple iCloud with an app-specific password and exposes
calendars, contacts, e-mail and notes as tools for LLMs. The tools are registered as a Home Assistant
LLM API, so they are available to every conversation agent that enables the API (Assist, Google Generative AI,
OpenAI, Ollama …) and to any MCP client (Claude, ChatGPT connectors, local agents) through Home Assistant's
MCP Server integration or the integration's own MCP endpoint. Inbox rules, push delivery and a daily overview
come with the separate extension Frieda Postfach.
The project is named after the maintainer's dog Frieda, who looks out of the cloud in the logo.
Features
| Area | Protocol | Read | Write |
|---|---|---|---|
| Calendar | CalDAV | list calendars, search/read events (recurrences expanded) | create, update (incl. RRULE) and delete events |
| Contacts | CardDAV | search (name, mail, phone, company …) and read contacts | create, update and delete contacts |
| IMAP + SMTP | mailboxes, search/filter, read mail (text, attachment list) | send/reply, mark read/flagged, move, trash – many uids at once | |
| Notes | IMAP folder Notes |
list/search/read notes | create, update and delete notes |
| Rules | – | with the extension Frieda Postfach | inbox rules, push, daily overview |
| Insights | all of the above | mailbox statistics, free time slots, birthdays, duplicate contacts | unsubscribe from newsletters, store attachments (receipts) |
Important note on Notes
Apple offers no interface for modern iCloud Notes (CloudKit, the default since iOS 9 / "upgraded notes") that
works with an app-specific password. The integration can therefore only read and write notes stored in the
IMAP folder Notes of the iCloud mail account (classic IMAP notes). If that folder does not exist, the note tools
say so. The other areas use official, stable protocols (CalDAV, CardDAV, IMAP, SMTP) and are fully usable.
Requirements
- Home Assistant 2026.10 or newer (the integration uses the current
llm.ToolAPI withprobatioschemas; older 2025 releases work through the built-involuptuousfallback but are untested). - An Apple ID with two-factor authentication and an app-specific password (appleid.apple.com → Sign-In and Security → App-Specific Passwords).
- iCloud Mail must be enabled for the Apple ID if you want e-mail and notes.
- Optional: Home Assistant's Model Context Protocol Server integration (
mcp_server) if you prefer it over the built-in endpoint.
Installation
Marketplace (recommended, Home Assistant 2026.11 or newer)
- Open this repository in the Marketplace, or go to Settings → Marketplace → Add from link and enter
nadeo360/friedafetch. - Install "Frieda" and restart Home Assistant.
Built into Home Assistant since 2026.11, the Marketplace replaces HACS and takes over existing HACS installations.
HACS (Home Assistant before 2026.11)
- HACS → Integrations → ⋮ → Custom repositories → URL of this repository, category Integration.
- Install "Frieda" and restart Home Assistant.
Manual
Copy custom_components/friedafetch into the custom_components directory of your Home Assistant configuration and
restart Home Assistant.
Upgrading to 2.0
Frieda 2.0 is a pure connector: inbox rules, push delivery, the daily overview and the birthday sensor moved to the
separate integration Frieda Postfach. Install it via the Marketplace or HACS and add
it for your account; existing rules, hit counters, run history and automation settings are picked up automatically.
Until then Frieda shows a repair notice for accounts with stored rules, and no rules run. The rule tools
(icloud_*_rule, icloud_run_rules, icloud_daily_overview) appear again as soon as Frieda Postfach is set up.
Upgrading from “iCloud MCP” (versions up to 1.0.x)
The project was renamed to Frieda with version 1.1.0; the integration domain changed from icloud_mcp to
friedafetch. Remove the old integration (Settings → Devices & services → iCloud MCP → Delete), update the HACS
custom repository to https://github.com/nadeo360/friedafetch, install Frieda and add it again with the Apple ID
and app-specific password. Rules and options are not migrated; MCP clients need the new endpoint
/api/friedafetch. The tool names (icloud_*) are unchanged. If an old custom_components/icloud_mcp folder is left
behind, Home Assistant may keep loading it instead of the current version (both declare the domain friedafetch);
Frieda detects this at startup and shows a repair issue – delete the folder named there and restart Home Assistant.
Setup
- Settings → Devices & services → Add integration → "Frieda".
- Enter the Apple ID and the app-specific password. Credentials are validated against CalDAV (mandatory) and IMAP (optional – if IMAP fails, the mail and note tools start disabled).
- Connect an MCP client, either via the built-in endpoint (see below) or via the core Model Context Protocol Server integration: there, under Configure, enable "all LLM APIs" or select "iCloud (Calendar, Contacts, Mail, Notes)" in addition to Assist.
- Optional for voice assistants: enable the iCloud LLM API in the conversation integration (e.g. Google Generative AI) under "Control Home Assistant".
Note on
mcp_server_http_transport(hass-mcp-server): that HACS integration ships its own fixed tool set and does not forward Home Assistant LLM APIs, so the iCloud tools do not appear there. Use the built-in endpoint or the core MCP Server integration instead; both can run side by side.
Options (Configure)
The options dialog has three sections: Tools and account, Security and guard rails and Approvals.
| Option | Effect |
|---|---|
| Calendar / Contact / E-mail / Note tools | show or hide tool groups |
| Read-only mode | hides every create/update/delete/send tool |
| Allow sending e-mails | hides icloud_send_mail when disabled |
| Allow deleting | hides all icloud_delete_* tools (except rule deletion) when disabled |
| Default maximum number of results | default list limit (1–200) |
| Sender address | From: for outgoing mail (default: Apple ID; must be an iCloud alias) |
| Attachment folder | where icloud_save_attachments (and Frieda Postfach rules) store files (default: a folder of its own, frieda_attachments in the configuration folder, which the media browser does not show; a chosen folder must be an allowed path) |
| Account label | short name used as tool suffix when several accounts are configured |
| Security section | quotas, recipient policy, protected calendars/mailboxes, hidden mailboxes (see Security) |
All tools carry MCP annotations (readOnlyHint, destructiveHint) so that clients in read-only mode can drop the
writing tools automatically.
Capabilities you switch off are not hidden silently: the LLM prompt (and the instructions of the built-in MCP
endpoint) lists what the administrator disabled, so the assistant can tell the user why it cannot send or delete
and where to enable it (Settings → Devices & services → Frieda → Configure). Likewise, active approvals are
announced so that an approval_required result is explained as "waiting for approval", not as an error.
Built-in MCP endpoint
The integration serves its tools directly at POST /api/friedafetch (MCP Streamable HTTP, stateless) and
authenticates with Home Assistant access tokens – no additional integration required.
- In Home Assistant open your profile → Security → Long-lived access tokens → Create token.
- Configure the client with the URL
https://<your-home-assistant>/api/friedafetchand the headerAuthorization: Bearer <token>.
For Claude Code (~/.claude.json) or Claude Desktop (claude_desktop_config.json) this looks like:
{
"mcpServers": {
"icloud": {
"type": "http",
"url": "https://<your-home-assistant>/api/friedafetch",
"headers": { "Authorization": "Bearer <token>" }
}
}
}
GET /api/friedafetch answers with a short status (name, version, tool count). Server-initiated streams and
sessions are not needed; every POST is handled on its own.
Several iCloud accounts
Add the integration once per Apple ID. The first account keeps the plain tool names (icloud_list_events); every
further account gets a suffix derived from its account label (option) or the local part of its Apple ID, for
example icloud_list_events_work. The LLM APIs are registered the same way (friedafetch, friedafetch_work), and
the panel offers an account selector. Each account has its own options.
Tools
| Tool | Description |
|---|---|
icloud_list_calendars |
calendars with ids |
icloud_list_events |
events in a time range (recurrences expanded), optional text filter |
icloud_get_event |
one event with details |
icloud_create_event |
create an event (all-day or timed, optional RRULE) |
icloud_update_event |
change fields of an event (duration kept when only start changes) |
icloud_delete_event |
delete an event |
icloud_search_contacts |
search contacts (empty query = alphabetical list) |
icloud_get_contact |
contact by uid |
icloud_create_contact |
create a contact |
icloud_update_contact |
change a contact (list fields replace the existing list) |
icloud_delete_contact |
delete a contact |
icloud_list_mailboxes |
mailboxes/folders |
icloud_search_mail |
filter mail (sender, subject, full text, date range, unseen, flagged) |
icloud_get_mail |
read a mail (text, optional HTML, attachment list, optional raw headers) |
icloud_send_mail |
send or reply (quote, In-Reply-To, copy in the sent folder) |
icloud_mark_mail |
read/unread, flagged/unflagged – one or many uids (uids) at once |
icloud_move_mail |
move to another folder – one or many uids with a single IMAP command |
icloud_delete_mail |
move to trash (or delete permanently when already in trash) – one or many uids |
icloud_approval_status |
outcome of an action that required human approval |
icloud_mailbox_stats |
top senders/domains, unread and newsletter share, rule coverage and rule suggestions |
icloud_unsubscribe |
unsubscribe from a newsletter (one-click https or unsubscribe e-mail) |
icloud_save_attachments |
store the attachments of a mail in <folder>/<subfolder>/<YYYY-MM>/ |
icloud_find_free_time |
free slots of a given length within working hours |
icloud_upcoming_birthdays |
birthdays of the contacts in the coming days (with age, if known) |
icloud_find_duplicate_contacts |
probable duplicates (same e-mail, phone or name) |
icloud_list_notes |
list/search notes |
icloud_get_note |
read a note |
icloud_create_note |
create a note |
icloud_update_note |
replace a note (it gets a new uid) |
icloud_delete_note |
delete a note |
Times are ISO 8601; naive times are interpreted in the Home Assistant time zone. All-day events use dates
(YYYY-MM-DD) with an inclusive end date. The mail tools icloud_mark_mail, icloud_move_mail and
icloud_delete_mail accept a uids list (up to 500) and process it with a single IMAP command, so cleaning up spam
is one call instead of one per message.
Panel
The integration adds "Frieda" to the Home Assistant sidebar (admins only, German/English following the HA language):
- Overview: whether the MCP endpoint is active (both URLs to copy – for the local address and, if set up, the external address and Home Assistant Cloud –, number of reading and writing tools, token rule), the MCP clients that connected recently (name and version from the MCP handshake), whether the LLM API is exposed by Home Assistant's own MCP server, and the state of Frieda Postfach (running, installed but not linked, not installed).
- Usage: tool calls today, in 7 and 30 days and in total, split into reading and writing, a 14-day chart, the most used tools, where the calls came from (Frieda endpoint, HA MCP server, Assist agents) and the hourly quotas. Only counters are stored, never arguments or results.
- Approvals: pending and decided requests (approve or deny with one tap, also from the companion app; the request shows "Sending …" until the result is in).
- Change log: everything Frieda changed in iCloud as a table grouped by day (e.g. "Mail moved · 3 messages · → Archive"), with search, filters for area and trigger, a result switch and selectable columns; a click on a row shows the error and the raw parameters, and for runs of Frieda Postfach the messages with a link to their timeline.
Tabs and widgets: three tabs keep the panel tidy – Overview (with the usage), Approvals (shown when approvals are on or there are entries; the tab counts the pending ones, so they stand out from the other tabs too) and Change log. On a keyboard 1–3 switch the tabs, / searches the change log and ? shows the keys; another tab glides in briefly (not with “reduce motion”). On the overview, Arrange in the title bar lets you drag the cards by the handle (or move them with the arrows), switch them between full and half width and hide them; tables offer a Columns menu. Rare actions such as clearing the log sit in a small ⋮ menu and always ask for confirmation. The layout and the last tab are stored per Home Assistant user in Home Assistant itself, so they survive restarts and follow you to other devices.
Live: the tables follow changes right away (new change-log entries, approvals, runs), without reloading the page; new rows light up briefly. After an update the panel offers a reload when it still runs the old code.
Pages: long tables show 5, 10, 25, 50 or all entries per page (remembered per table); search and filters always cover all entries.
Frieda UI: both panels use one shared design library (/friedafetch_static/ui.js): colours from the Home
Assistant theme, buttons, chips, tables, menus, dialogs and widgets. Frieda Postfach loads it from Frieda, so every
module looks and behaves the same. It also covers accessibility: the focus stays in place when a panel redraws,
dialogs keep the focus inside, notices and search hits are read out, symbols have names for screen readers, and
coloured text keeps WCAG AA contrast in light and dark themes.
The panel has no external dependencies and talks to the integration via WebSocket commands (friedafetch/accounts,
friedafetch/overview, friedafetch/usage/reset, friedafetch/approvals/*, friedafetch/audit/*).
Attachments and unsubscribing
- Attachments:
icloud_save_attachmentsstores the attachments of a mail below the attachment folder, sorted by month and named<date>_<sender>_<file>. Identical files are not stored twice, small images (logos, signatures) are skipped. By default they go tofrieda_attachmentsin the configuration folder, which no media source shows. A folder you choose must be allowed by Home Assistant (allowlist_external_dirs); a media folder is allowed too, but there every Home Assistant user can open the attachments in the media browser. Until 2.0.27 the default was<media>/frieda: a repair offers to move what is stored there, or to keep that folder on purpose. - Unsubscribe:
icloud_unsubscribeuses theList-Unsubscribeheader: one-click https (RFC 8058) first, then an unsubscribe e-mail (only when sending is allowed; it counts against the sending quota and needs approval if sending does). Links that require a web page are returned for you to open.
Extensions
Frieda only acts when an AI client or you call it. Everything that runs on its own lives in extensions that attach to a Frieda account, reuse its connection and guard rails, and add their tools to it:
- Frieda Postfach (
friedafetch_mail): inbox rules with push delivery (IMAP IDLE), receipts via rules, the daily overview, a birthday sensor and the rule tools.
Frieda MCP questions
What tools does Frieda MCP provide?
It exposes 30 tools, including icloud_list_calendars, icloud_list_events, icloud_get_event, icloud_create_event, icloud_update_event.
What iCloud services does Frieda support?
Frieda supports calendars, contacts, e-mail, and notes.
Can I use modern iCloud Notes with this integration?
No, the integration can only read and write notes stored in the classic IMAP folder named 'Notes' because Apple provides no interface for modern CloudKit notes via app-specific passwords.