noteful-mcp

Let an AI agent read and write your Noteful notebooks.

An MCP server for the iPad note-taking app Noteful. It sees your pages the way the app draws them, knows what you highlighted and what you hid under tape, and writes new pages in real, editable Noteful ink: handwriting, highlighter, hand-drawn diagrams. Everything runs on your own computer.

Beta. Noteful's format is reverse engineered. Reading never changes your library and writing only creates new files, but expect rough edges, and please report pages that read or render wrong.

Features

• Read every notebook of your library live (with Noteful for Mac) or from exported .noteful files: page images, typed and PDF text search, highlighted passages, taped answers.
• Write notebooks and pages from Markdown in natural handwriting, annotate existing pages, and draw diagrams. The result is real Noteful ink: lasso it, recolour it, erase it.
• Study notes look: composed summary pages and dark tree pages with titles, cards, columns, colour zones, sticky notes and pastel-coloured diagrams the agent draws as SVG.
• Copy a page design: have an image model draw the page, then the server copies it into ink, drawings included: same layout, sizes and colours, correct words (optional, with your own Google key).
• Science-ready handwriting: Greek letters, super/subscripts, arrows and math signs.
• Private by design: no cloud service of ours; nothing leaves your computer unless you turn on mockups. Your library and source files are never modified.

The .noteful format is undocumented; it was reverse engineered from real notebooks and checked against the app, see docs/FORMAT.md.

Quick start

You need uv, which brings its own Python. Add the server to your MCP client; for Claude Code:

claude mcp add -s user noteful -- uvx --from git+https://github.com/openninoor/noteful-mcp noteful-mcp

Other clients (Claude Desktop, Gemini CLI, …) run the same command as a stdio server. ChatGPT only connects to remote (HTTPS) MCP servers; built-in support is coming, until then you can put the server behind your own HTTPS endpoint with any stdio-to-HTTP MCP bridge. Then check what the server can see on this computer:

uvx --from git+https://github.com/openninoor/noteful-mcp noteful-mcp doctor

How it works

iPad (Noteful) ──iCloud──▶ Mac (Noteful for Mac, same library) ──▶ noteful-mcp ──▶ agent
                                                                       │
iPad ◀── Files: "Noteful MCP" folder ◀── written .noteful files ◀──────┘

With a Mac (Apple silicon, recommended). Install Noteful from the App Store on the Mac and sign in with the same Apple ID as the iPad. The server reads that synced library directly: every notebook, always current, nothing to export. If macOS blocks access, doctor says so: give the app that runs the server (Terminal, Claude) Full Disk Access. If the Mac lags behind the iPad, quit and reopen Noteful on the Mac.

Without a Mac (Windows, Linux, Intel Mac). Export notebooks from the iPad as .noteful files into a synced folder (iCloud Drive/Noteful, or Dropbox / Google Drive via NOTEFUL_ROOTS). All tools work on those files; export again after changes.

Writing back. The server never writes into your library or over a source file. It writes a new .noteful file into iCloud Drive/Noteful MCP and, on a Mac with Noteful, opens it in Noteful right away; Noteful asks where it goes and syncs it to the iPad:

• a new notebook (create_notebook): Create New Notebook;
• new pages or a clean copy for a notebook in your library (add_pages, clean_copy), or a marked-up copy of one of its pages (write_on_page): open that notebook at the page, then Add to Current Notebook › After current page. The tool's reply says which to pick.

Without a Mac, open the file on the iPad from the Files app instead. Pass open_in_noteful=False (or set NOTEFUL_OPEN=0) to only write the file.

Configuration

Variable	Default
NOTEFUL_ROOTS	Folders scanned for .noteful files, separated by : (; on Windows). iCloud Drive's Noteful, Downloads and Noteful MCP; ~/Noteful without iCloud Drive.
NOTEFUL_OUTPUT_DIR	Where written notebooks go: iCloud Drive/Noteful MCP.
NOTEFUL_LIBRARY	Noteful for Mac's library (its container Documents folder).
GEMINI_API_KEY	Optional, for design_mockup: a Google AI Studio key.
NOTEFUL_VERTEX_PROJECT	Optional, instead of the key: a Google Cloud project, used through Vertex AI with your Google credentials (NOTEFUL_VERTEX_LOCATION, default global).
NOTEFUL_IMAGE_MODEL	Image model for mockups: gemini-3.1-flash-lite-image.

To use a Mac that stays at home from another machine, run the server there over SSH: ssh user@host uvx --from git+https://github.com/openninoor/noteful-mcp noteful-mcp.

Tools

Read
live_library	Folder and notebook tree of the live library, with live:<id> refs
search_text	Search the typed and PDF text Noteful indexed (render pages to read handwriting)
list_notebooks, library_tree	Exported .noteful files and their folder tree
notebook_info	Dates, folder and per-page details: background, strokes, highlights, tapes, images
render_page, render_region	Page image or zoomed crop; reveal_tapes=True shows what tape hides
page_marks	Highlighted regions and tapes with colour, state and position; crops=True zooms in
page_layout	The handwriting as numbered items with positions (and a numbered image), to aim marks
page_ink	Stroke counts per tool, colours, widths, inked area
export_pdf, extract_files	The notebook as PDF; embedded PDFs and images

Write
create_notebook	A new notebook from Markdown, written by hand
add_pages, clean_copy	Add pages to a notebook; rewrite a messy page neatly right after it
write_on_page	Mark up a page: ticks, circles, notes, highlighter, drawings, tape (e.g. grade a quiz)
example_pages	Example pages and drawings to imitate, with source and preview
design_mockup	A picture of the page from an image model, on your own key (optional)
mockup_grid	A mockup with a pixel grid (and zoom) to read positions off it
design_page	Pages that copy mockups in ink: text, cards, bands, notes, traced drawings
rename_notebook, output_folder

A typical study session: page_marks finds what you highlighted and taped, the agent reads those regions and writes you a quiz with create_notebook. You answer it on the iPad; the agent reads your answers with render_page, finds each option with page_layout and grades the page with write_on_page: ticks, a circle around a wrong pick, the right answer highlighted and a score.

Study notes look

Written pages default to look="study", distilled from a frame-by-frame study of a well-known medical-student note-taking video (docs/STYLE.md): composed summaries on ivory paper (theme="light") and fast question and tree pages on black (theme="dark"). The pages at the top come from the gallery of example pages.

# THE **CARDIAC** CYCLE
_Cardiology · lecture 4_
>> [coral] SYSTOLE → HIGH PRESSURE: the muscle **contracts** || [sky] DIASTOLE → LOW PRESSURE: it **refills**
!columns 55
!draw 480
<svg viewBox="0 0 400 300"> ... organ outline, parts, <text> labels ... </svg>
!end
!col
## **Electro**physiology
The **SA node** fires an ==action potential== ((~70 per minute)).
1. SA node starts the beat
2. AV node delays it
!end
!zone sky
!stat 70 beats per minute at rest
!sticky [yellow] Remember: valves move **passively**, only with pressure.
!end

• Titles: thick block capitals with a soft shadow and stripe bars, the **word** in colour, or two lines (TOP // BIG) on a marker band; :sun:-style doodles.
• A pen-weight hierarchy (title > headings > felt-tip body) and mixed-case body text with colour, highlighter, pills and grey details only where they mean something.
• Cards, two-column layouts, full-width colour zones, taped sticky notes, big numbers, circled steps, !map tree diagrams with hollow arrows and ↳ lists.
• !draw diagrams: the agent draws organs, cells, graphs or models as plain SVG; outlines become hand-drawn ink, fills pastel highlighter colouring (real Noteful highlighter strokes, editable on the iPad), <text> labels handwriting. write_on_page takes the same SVG.
• Science writing: Greek letters, T^4, m^{-2}, CO_2, arrows, ≈ ± ° ≤ ≥.

Examples for the agent

Agents write better pages when they can see good ones. The server ships a gallery of example pages and drawings (summary, clean copy, quiz, tree; organ, cell, graph, process, probability tree) with their source and a preview, and the rules that keep pages from looking generated:

• the example_pages tool (works with every client),
• resources noteful://examples, noteful://examples/{name}, noteful://examples/{name}/preview and noteful://style,
• prompts that start a task with the right example: summary_page, quiz, grade_quiz, clean_copy_page, tree_page.

Handwriting fonts: patrick (default, rounded print) and caveat (quick slanted hand) are single-line pen fonts derived from the OFL fonts Patrick Hand and Caveat; titles use a block-letter version of Patrick Hand. Options: hand = neat / natural / messy, pen = fineliner / ballpoint. look="classic" gives a plain notebook page instead.

Copying a page design

Composing a beautiful page from rules has limits; image models know a far wider range of layouts. So the server can work from a picture instead: an image model draws the page (design_mockup), the agent lists what is on it in the picture's pixels, with the correct words since image models garble small text, and design_page redraws it as Noteful ink. Drawings are traced straight from the picture: outlines become pen strokes, colour areas highlighter (or pen, for colours highlighter cannot show), so they keep the model's quality and stay editable.

• look="rich" for summary pages, look="calm" for plain lecture notes; mix them.
• Pass the previous page's mockup as reference and a multi-page note keeps one style.
• A spec part can be drawn at scale 0.5: two mockups fill one page in half-size handwriting, paragraphs re-wrapped to the page width.
• Any picture works, not only generated ones: a page the user likes, a screenshot.
• Text never runs into its neighbours: lines shrink to their room, and text that still overlaps is pushed down together with what is under it.

Mockups run on your own Google account: set GEMINI_API_KEY or NOTEFUL_VERTEX_PROJECT and install the extra (uvx --from 'noteful-mcp[design] @ git+https://github.com/openninoor/noteful-mcp' noteful-mcp). The page content you describe is sent to Google to draw the picture; nothing else is. We built and tuned this with Nano Banana 2 Lite (gemini-3.1-flash-lite-image): fast, cheap (about 4 US cents a page) and good enough to copy from. A larger image model will likely give better pages; set NOTEFUL_IMAGE_MODEL to try one.

Development

See CONTRIBUTING.md. In short: uv sync, uv run pytest, uv run ruff check ., and uv run python examples/build.py to build the gallery pages.

License

MIT. The fonts in src/noteful_mcp/fonts are under the SIL Open Font License (see the OFL*.txt files next to them).

Noteful is a trademark of its owners; this project is not affiliated with or endorsed by them. Use it with your own notebooks.