Apple MCP Calnot

Local MCP/WebUI bridge for iCloud Notes.

The app keeps an authenticated iCloud Notes browser session alive, syncs notes into MongoDB, and exposes note operations through MCP.

Commands

make start
make stop
make clean

• make start starts Docker Compose without rebuilding and preserves volumes/session state.

• make stop stops containers and preserves volumes/session state.

• make clean removes containers and volumes. This wipes MongoDB and the browser profile, so iCloud login will be required again.

To apply code changes to the app container while preserving volumes/session:

docker compose up -d --build mcp-notes

Related MCP server: io.github.henilcalagiya/mcp-apple-notes

Login Flow

1. Open the WebUI at http://localhost:3000.

2. Click Generate Code.

3. Copy the generated code.

4. Log into iCloud in the embedded browser view.

5. Click Start.

6. After start, WebUI/API/MCP access requires the generated code.

The browser profile is persisted in the Docker volume mounted at /data, so normal make stop / make start should keep the iCloud session.

Current Architecture

WebUI / MCP
    |
NotesProcessor
    |
BrowserController
    |
Playwright authenticated iCloud page
    |
iCloud Notes iframe
    |
window.NotesApp
    |
NotesApp.dataManager.allNotes
    |
note.getTopoText()
    |
MongoDB

Playwright is still useful, but not for OCR or visual scraping. It is used to keep an authenticated iCloud page open and to evaluate JavaScript inside the iCloud Notes iframe.

iCloud Notes Discovery

We originally saw note content rendered through a canvas-like/custom editor surface. OCR was rejected because it is unreliable and loses structure. The important discovery is that the visible editor is only the presentation layer; the real Notes model is available in the running iCloud web app.

The path to discovery was:

1. The top-level iCloud HTML showed that /notes bootstraps a child application iframe.

2. The bootstrap script resolves /notes to notes3.

3. It creates an iframe with id early-child.

4. That iframe loads:

https://www.icloud.com/applications/notes3/current/en-us/index.html?rootDomain=www...

5. Safari Apple Events inspection confirmed the top page has that iframe.

6. Inspecting document.querySelector('iframe').contentWindow showed these globals:

CloudKit
NotesApp

7. Drilling into window.NotesApp showed:

NotesApp.dataManager
NotesApp.mainViewModel
NotesApp.rootViewController

8. NotesApp.dataManager.allNotes contains the loaded note models.

9. NotesApp.mainViewModel.selectedNote points to the selected note.

10. Each note model exposes Notes-specific fields and helpers:

id
recordName
Title
Snippet
TopoTextString
getTopoText()
CreationDate
ModificationDate
zoneID

note.getTopoText() loads/decodes the full note body using Apple's own app code. This avoids OCR, canvas parsing, and reimplementing Apple's TopoText decoder.

CloudKit vs NotesApp

CloudKit is Apple's generic iCloud database transport layer. It talks to endpoints such as:

ckdatabasews/.../database/1/com.apple.notes/production/private/records/query
ckdatabasews/.../database/1/com.apple.notes/production/private/records/lookup
ckdatabasews/.../database/1/com.apple.notes/production/private/changes/zone

NotesApp is the running iCloud Notes web application loaded inside the iframe. It wraps CloudKit, owns UI/application state, manages folders and notes, and decodes Notes-specific content.

For this project, NotesApp is the preferred first integration point because it already exposes decoded note models:

const notesWindow = document.querySelector('iframe').contentWindow;
const notes = notesWindow.NotesApp.dataManager.allNotes;
const body = String(await notes[0].getTopoText());

Direct CloudKit access is still useful later for lower-level sync/write operations, but it requires handling raw record fields, assets, zipped protobuf TopoText, and write semantics.

Stable Note Identity

iCloud note URLs contain the CloudKit identity encoded as base64:

/notes/note/<base64>

Decoding the URL path gives:

Private::Notes::currentUser::<recordName>

Example observed from Safari:

Private::Notes::currentUser::ADAC358D-E303-4639-A5C2-192AE0726967

The sync stores this metadata as cloudKit:

{
  "recordId": "Private::Notes::currentUser::<recordName>",
  "database": "Private",
  "zoneName": "Notes",
  "ownerName": "currentUser",
  "recordName": "<recordName>"
}

Sync Strategy

The current read path is:

1. Open or reuse the authenticated iCloud Notes page.

2. Find the Notes iframe.

3. Evaluate JavaScript inside the iframe.

4. Read NotesApp.dataManager.allNotes.

5. Filter deleted/trash notes.

6. Await note.getTopoText() for each note.

7. Store title, body, URL identity, and CloudKit metadata in MongoDB.

The older DOM/card scraper remains only as a fallback.

Write Strategy

Safari runtime testing confirmed that create, update, and delete can be driven through NotesApp directly.

Observed working methods:

const app = document.querySelector('iframe').contentWindow.NotesApp;
const dataManager = app.dataManager;
const Note = app.mainViewModel.selectedNote.constructor;

Create:

const note = Note.createNoteWithTitleText(fullText, folder);
dataManager.userDidCreateNote(note);
await note.save(true);

Update:

const replacement = Note.createInitialTopoTextString(nextText);
dataManager.topoTextManager.load(note.id, replacement);
note.userDidChangeTopoText();
await note.save(true);

Delete:

await note.deleteOrMoveToRecentlyDeletedAsNeeded();

The delete path moves normal private notes to Recently Deleted, matching the web app behavior.

The probe used a temporary note and verified:

• create through Note.createNoteWithTitleText

• update through topoTextManager.load and userDidChangeTopoText

• delete through deleteOrMoveToRecentlyDeletedAsNeeded

• stable CloudKit identity persisted as Private::Notes::currentUser::<recordName>

MCP writes now use this runtime path first. UI keyboard fallback remains only as a backup for append/create.

What Not To Do

• Do not use OCR/Tesseract for note bodies.

• Do not treat canvas pixels as the source of truth.

• Do not identify notes by title; titles are mutable and non-unique.

• Do not use make clean unless you intentionally want to wipe browser and database persistence.

Validation

npm run check

MCP Endpoint

The MCP server is exposed at:

POST /mcp

Authentication accepts any of:

Authorization: Bearer <generated-code>
X-Auth-Token: <generated-code>
?token=<generated-code>
apple_mcp_token cookie

The server advertises these MCP tools:

listNotes
getNote
searchNotes
createNote
appendNote
deleteNote

For ChatGPT testing, expose the app over HTTPS and configure the MCP URL as:

https://your-domain.example/mcp?token=<generated-code>

Using the token in the URL is convenient for testing because the current server uses a generated static code, not OAuth. For a durable public deployment, prefer adding OAuth or a reverse proxy that injects the bearer token server-side, so the code is not stored in connector URLs or logs.