apple-notes-reminders-mcp

Ein MCP-Server (Model Context Protocol), der Apple Notes und Apple Reminders für MCP-kompatible Clients (z. B. Claude Desktop) auf macOS bereitstellt.

Was er tut

Der Server registriert eine Reihe von Werkzeugen zum Lesen und Schreiben von Notizen und Erinnerungen. Die Notizenwerkzeuge decken Auflisten, Suchen (einschließlich erkannter Text in Bildanhängen), Lesen, Erstellen, Aktualisieren, Verschieben und Löschen von Notizen und Ordnern ab, sowie Tags, Anheftungsstatus, Bildanhänge und den Papierkorb. Die Erinnerungenwerkzeuge decken die entsprechenden Operationen ab, plus Unteraufgaben, Stapelerstellung, Erledigung, Fälligkeitsdaten, Kennzeichnung, Wiederholung, Orts-/Vorab-Alarme, gespeicherte Filteransichten, Vorlagen und massenhafte wortbasierte Filter.

Related MCP server: apple-reminders-mcp

Architektur

Die beiden Domänen werden über unterschiedliche Mechanismen gelesen und geschrieben:

Lesevorgänge erfolgen nach Möglichkeit über SQLite. Notizen werden direkt aus der lokalen NoteStore-Datenbank gelesen:

~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite

Die Datenbank wird an einen temporären Speicherort kopiert und schreibgeschützt geöffnet, sodass der Live-Store nie berührt oder gesperrt wird. Notiztexte werden als gzippter Protobuf-Blob in ZICNOTEDATA.ZDATA gespeichert; der Dekoder dekomprimiert diesen und navigiert deterministisch durch die Protobuf-Struktur, um Text und Formatierungsmetadaten zu extrahieren.

Schreibvorgänge erfolgen über AppleScript (osascript). Die NoteStore-Datenbank gehört der Notes.app und kann nicht sicher von außen beschrieben werden, daher werden Erstellungs-, Aktualisierungs-, Lösch- und Verschiebeoperationen an Notes.app per AppleScript delegiert. Erinnerungs-Unteraufgaben verwenden ebenfalls AppleScript, da die öffentliche EventKit-API diese nicht bereitstellt.

Dekodierung von Notiztexten

Das korrekte Lesen eines Notiztextes ist die heikle Stelle dieses Projekts. Der Text ist kein Klartext – es ist eine Protobuf-Nachricht innerhalb des gzippten Blobs. Der Dekoder:

1. Dekomprimiert ZDATA und navigiert deterministisch zur Notiztext-Nachricht (document → Feld 2 → Feld 3), dann liest er den Text-String (Feld 2). Dies ersetzte eine frühere Heuristik, die nach dem „saubersten" String-Kandidaten suchte und für Notizen mit Checklisten beschädigte Binärdaten zurückgab.

2. Durchläuft die wiederholten Absatzmetadaten pro Span, um Checklistenelemente und deren erledigten/nicht erledigten Status zu erkennen, und stellt erledigten Elementen - [x] und nicht erledigten - [ ] voran.

Zwei Details sind für die Korrektheit wichtig:

• Varints werden mit Multiplikation (* 2 ** shift) anstelle des <<-Operators akkumuliert, da JavaScripts bitweise Verschiebung auf 32 Bit kürzt und große Offsets beschädigt.

• Span-Längen werden in UTF-16-Codeeinheiten gemessen, so wie Apple sie speichert, sodass Checklistenmarkierungen auch dann ausgerichtet bleiben, wenn der Text mehrbyte Zeichen oder Emojis enthält.

Wenn die SQLite-Dekodierung aus irgendeinem Grund fehlschlägt, greift notes_get auf das Lesen des Notiztextes per AppleScript zurück, was sauberen Text zurückgibt, aber den Checkbox-Status nicht wiederherstellen kann (Apples AppleScript-body-Eigenschaft kodiert ihn nicht).

Anhänge

Bildanhänge werden aus den ICAttachment/ICMedia-Zeilen von ZICCLOUDSYNCINGOBJECT gelesen (dynamisch über Z_PRIMARYKEY/Z_ENT aufgelöst, nicht fest codiert, da die numerischen Entitäts-IDs und die Spaltennamen ZACCOUNT*/ZPARENT zwischen macOS-Versionen variieren). Die eigentliche Datei liegt auf der Festplatte unter:

~/Library/Group Containers/group.com.apple.notes/Accounts/{account}/Media/{media id}/{generation}/{filename}

notes_get gibt für jeden Anhang die ID, den Dateinamen, den Typ, den aufgelösten Dateipfad und eventuell erkannten OCR-Text zurück; notes_get_attachment ruft einen Bildanhang als MCP-Bildinhaltsblock ab. notes_search bezieht OCR-Text in den Suchkorpus ein, sodass Text, der nur in einem Screenshot vorkommt, auffindbar ist. Das Hinzufügen eines Anhangs wird nicht unterstützt – siehe „Bekannte Einschränkungen" unten.

flagged bei Erinnerungen und andere nur per AppleScript lesbare Werte

Die öffentliche EventKit-API hat keine flagged-Eigenschaft, daher wird sie vollständig per AppleScript gelesen und geschrieben und per ID in die von EventKit stammenden Reminder-Objekte eingefügt. Ein anwenderweiter geflagter Scan ist vergleichsweise langsam (AppleScripts IPC-Overhead pro Eigenschaft), daher enthalten reminders_list/reminders_search nur dann flagged, wenn sie auf eine einzelne Liste eingeschränkt sind; verwenden Sie reminders_query_where/reminders_view mit einem expliziten flagged-Filter, wenn Sie sie über alle Listen hinweg benötigen.

Caching

notesStore.ts speichert die offene SQLite-Verbindung, das erkannte Schema und den dekodierten Text jeder Notiz zwischen, alles ungültig gemacht durch Vergleich der Änderungszeit der Quelldatei (und ihrer -wal/-shm-Seitendateien) bei jedem Aufruf – ein Schreibvorgang in den Live-NoteStore macht den Cache immer ungültig, daher ist dies ein reiner Leistungsgewinn, kein Risiko von Veralterung. Dekodierte Texte werden zusätzlich mit (Z_PK, Änderungsdatum) indiziert, sodass eine bearbeitete Notiz einen neuen Cache-Eintrag und keinen veralteten Treffer erhält.

Anforderungen & Berechtigungen

• macOS (getestet auf macOS 26 / Tahoe)

• Node.js 18+ (verwendet better-sqlite3 für SQLite-Zugriff)

• Notes.app und Reminders.app eingerichtet und in einem Konto angemeldet

• Automatisierungsberechtigung: Die Host-Anwendung (z. B. Claude Desktop) muss die Berechtigung haben, Notes und Reminders zu steuern – macOS fordert bei der ersten Nutzung dazu auf, oder sie kann unter Systemeinstellungen › Datenschutz & Sicherheit › Automation gewährt werden

• Vollzugriff auf die Festplatte: Erforderlich, damit die Host-Anwendung die NoteStore-Datenbank unter ~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite lesen kann – unter Systemeinstellungen › Datenschutz & Sicherheit › Vollzugriff auf die Festplatte gewähren

Hinweise zu macOS-Versionen

Spaltennamen und numerische Entitäts-IDs innerhalb von ZICCLOUDSYNCINGOBJECT verschieben sich zwischen macOS-/Notes.app-Versionen (z. B. wurden ZACCOUNT1 bis ZACCOUNT8 auf verschiedenen Systemen als der aktive Ordner→Konto-Fremdschlüssel gesehen, und Z_ENT-Werte für ICAccount/ICAttachment/ICMedia sind nicht stabil). Die detectSchema()-Methode von notesStore.ts erkennt diese bei jedem Cache-Fehler neu, anstatt sie fest zu codieren – siehe die Kommentare dort, bevor Sie einen neuen Spaltennamen fest codieren. Dies wurde entwickelt und gegen macOS 26 (Tahoe) getestet; die Erkennungslogik ist so geschrieben, dass sie ältere Versionen toleriert, aber nicht gegen diese verifiziert.

Installieren

npm install
npm run build

Ausführen

npm start

Oder registrieren Sie dist/index.js als MCP-Serverbefehl in der Konfiguration Ihres Clients.

Projektaufbau

src/
  index.ts        MCP server + tool registrations
  notes.ts        Notes tool implementations (SQLite reads, AppleScript writes)
  notesStore.ts   NoteStore SQLite access + protobuf body decoder
  reminders.ts    Reminders tool implementations + local template/saved-view storage
  applescript.ts  Shared runAppleScript() helper (argv-only, never string-spliced)
  markdown.ts     Markdown -> Notes-compatible HTML converter
swift/
  reminders-daemon.swift  Persistent EventKit daemon (NDJSON over stdio)
scripts/
  test-phase2.mjs           Protobuf/checklist decoder tests (+ pinned full-pipeline fixtures)
  test-markdown.mjs         Markdown -> HTML converter tests
  test-schema-detection.mjs Schema-detection sanity checks against the live DB
dist/             Compiled output (generated by `npm run build`)

Erinnerungsvorlagen und gespeicherte Filteransichten (reminders_save_template, reminders_save_view) werden als JSON unter ~/.apple-notes-reminders-mcp/ gespeichert – es gibt kein serverseitiges Datenbank dafür, da EventKit kein eigenes Konzept dafür hat.

Hinweise zu Berechtigungen und Datenschutz

Alle Lesevorgänge erfolgen lokal gegen eine temporäre Kopie der lokalen NoteStore-Datenbank. Nichts wird vom Server selbst an das Gerät gesendet. Der Server benötigt die gleichen Zugriffe, die ein Benutzer bereits auf seine eigenen Notizen und Erinnerungen hat.

Testen

npm run build && node scripts/test-phase2.mjs           # protobuf/checklist decoder
npm run build && node scripts/test-markdown.mjs          # markdown -> Notes-HTML converter
npm run build && node scripts/test-schema-detection.mjs  # schema detection sanity (live DB)

test-markdown.mjs ist vollständig deterministisch. Die Unit-Test-Abschnitte von test-phase2.mjs (Varint-Sicherheit, Checklisten-Grenzfälle, angeheftete Full-Pipeline-Fixtures) sind in sich geschlossen; der letzte Abschnitt „Real DB notes" und alle Teile von test-schema-detection.mjs lesen die echte, aktive Notes-Datenbank und werden nur mit Vollzugriff auf die Festplatte und tatsächlichen Notizdaten bestehen – erwarten Sie Fehler/Probleme dort auf einem anderen Rechner als dem des ursprünglichen Autors (test-phase2.mjs’s DB-Abschnitt verweist speziell auf Notiz-IDs, die nur in dieser einen Bibliothek existieren).

Bekannte Einschränkungen

• Die Neuordnung von Ordnern ist nicht implementiert. Es wurde live bestätigt, dass Notes.apps AppleScript move <folder> to <folder> unzuverlässig ist – es wirft zeitweise Fehler (item N of every folder kan niet worden opgevraagd) oder tut stillschweigend nichts, unabhängig davon, ob der Ordnerverweis über folder id, einen whose-Filter oder einen manuellen Scan kommt. Ordner umbenennen und löschen sind zuverlässig und implementiert; einen Ordner unter einen anderen zu verschieben ist nicht implementiert, da ein Werkzeug, das unvorhersehbar fehlschlägt, schlimmer ist als keines. Das Umbenennen/Löschen eines verschachtelten Ordners (der über die Notes.app-Oberfläche erstellt wurde, nicht durch diesen Server) wird unterstützt – übergeben Sie seinen vollständigen Pfad "Eltern/Kind".

• Es gibt keine Möglichkeit, über diesen Server einen Anhang hinzuzufügen. Das Lesen von Anhängen wird vollständig unterstützt (siehe oben). Das Hinzufügen erfordert die Notes.app-Oberfläche – eine Brücke über Shortcuts-CLI (shortcuts run <name> -i <path>) wurde untersucht und als nicht praktikabel für ein Zero-Setup-Werkzeug befunden: Es akzeptiert genau eine Eingabedatei ohne Möglichkeit, gleichzeitig eine Zielnotiz zu übergeben, und die shortcuts-CLI kann nur eine bereits vorhandene Verknüpfung ausführen, keine erstellen. Siehe den Kommentar am Anfang von notes.ts für die vollständige Ausarbeitung.

• Audioprotokolle werden nicht angezeigt. OCR-Text von Bildanhängen wird angezeigt (notes_get, notes_search). Die DB hat auch eine Spalte in der Form eines Audioprotokolls (ZTEMPORARYTRANSCRIPTDATA), aber es ist ein undurchsichtiger Blob, und es waren keine Audioanhänge verfügbar, um das Format dagegen zu reverse-engineeren – das bleibt einem zukünftigen Mitwirkenden mit echten Testdaten überlassen.

• Ein gelöschter Ordner kann weit über eine Minute brauchen, um aus notes_list_folders zu verschwinden. Live bestätigt: Das Löschen selbst ist in Notes.app sofort sichtbar (und sofort für AppleScript sichtbar), aber das Soft-Delete-Flag der SQLite-Zeile kann 60s+ hinterherhinken, anscheinend in Erwartung eines iCloud-Synchronisations-Roundtrips – viel länger als die typischen ~5s SQLite-Verzögerung, die bei Umbenennungen/Erstellungen anderswo beobachtet wird. Dies kann der Server nicht verkürzen; dokumentiert in notesStore.ts für jeden, der nach einem vermeintlichen Cache-Fehler sucht.

• „Smarte Ordner" (ursprüngliche Formulierung von PLAN) existieren als allgemeines Notes.app-Feature nicht wirklich so, wie Reminders sie hat – die DBs ZFOLDERTYPE=1 unterscheidet nur den eingebauten Ordner „Zuletzt gelöscht" von normalen. Schreibgeschützte Unterstützung für dieses Flag existiert (isSmartFolder auf notes_list_folders); tagbasierte Gruppierung (notes_list_tags) ist die nähere Analogie zu einer „gespeicherten intelligenten Liste" für Notizen.

• „Listenabschnitte" bei Erinnerungen (ein neueres Gruppierungsfeature von Reminders.app) werden nicht gelesen – EventKit macht sie nicht zugänglich, und dies würde bedeuten, den separaten lokalen Speicher von Reminders zu reverse-engineeren, was in diesem Durchlauf nicht versucht wurde.

Werkzeuge

Notes

Erinnerungen