An MCP (Model Context Protocol) server that gives Claude access to your GoodNotes notebooks via iCloud Drive — including OCR of handwritten notes using Apple's Vision framework (the same engine as iPhone Live Text).
| Tool | Description |
|---|---|
list_notebooks |
Find all .goodnotes files synced to iCloud Drive |
list_notebooks_with_export_status |
Show which notebooks have full multi-page OCR available |
ocr_notebook |
OCR a notebook — handwriting, equations, typed text |
search_notebook_ocr |
Search for a term across OCR'd content |
get_notebook_thumbnail |
Return the first-page thumbnail as base64 JPEG |
GoodNotes .goodnotes files are zip archives. The handwriting stroke data is a proprietary protobuf — not directly parseable. The server uses two paths:
Path 1 — Thumbnail OCR (works immediately, first page only):
Extracts thumbnail.jpg from the zip, upscales 3× with Lanczos, runs VNRecognizeTextRequest at accurate level.
Path 2 — Exported PDF OCR (all pages, higher accuracy):
If a PDF with the same name exists alongside the .goodnotes file, Quartz renders each page at 2× scale, then Vision OCRs each rendered image.
To enable Path 2: in GoodNotes on iPad/iPhone → ··· → Export → PDF → save to iCloud Drive.
- macOS 12+ (uses Apple Vision and Quartz frameworks)
- Python 3.11+
uv(recommended) or pip- GoodNotes notebooks synced to iCloud Drive
git clone https://github.com/YOUR_USERNAME/goodnotes-mcp
cd goodnotes-mcp
uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python mcp pypdf pyobjc-framework-Vision pyobjc-framework-Quartz Pillowclaude mcp add goodnotes -s user -- \
/path/to/goodnotes-mcp/.venv/bin/python \
/path/to/goodnotes-mcp/server.pyAdd to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"goodnotes": {
"command": "/path/to/goodnotes-mcp/.venv/bin/python",
"args": ["/path/to/goodnotes-mcp/server.py"]
}
}
}The server reads .goodnotes files directly from iCloud Drive — no API keys, no GoodNotes account access, no network requests. iCloud sync handles keeping files up to date.
notebook.goodnotes (zip archive)
├── thumbnail.jpg ← rendered first-page preview (OCR path 1)
├── attachments/UUID ← original imported PDF background
├── notes/UUID ← handwriting strokes (proprietary protobuf)
├── index.notes.pb ← page metadata
└── index.search.pb ← search index
The notes/UUID binary stores vector stroke paths — coordinates, pressure, color — not rendered pixels. This is why Vision OCR runs on the thumbnail or an exported PDF rather than the stroke data directly.
MIT