How do I install Noteful?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Noteful need an API key?

No required environment variable is listed on this record.

What transport does Noteful use?

Noteful runs locally over stdio.

When was Noteful last checked?

Last checked 2026-10-27. MCP server that lets AI agents read and write Noteful (iPad) notebooks in real, editable handwriting ink

Noteful MCP server

noteful-mcp

Let an AI agent read and write your Noteful notebooks.

Pages written by the server: cell biology notes, a quiz, a dark answer page with a tree diagram, solar radiation notes

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

A page mockup from an image model next to the same page copied into Noteful ink

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.

noteful-mcp

Let an AI agent read and write your Noteful notebooks.

Pages written by the server: cell biology notes, a quiz, a dark answer page with a tree diagram, solar radiation notes

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

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 ◀──────┘

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`

Study notes look

# 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

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.

Copying a page design

A page mockup from an image model next to the same page copied into Noteful ink

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.

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.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Noteful?

Does Noteful need an API key?

What transport does Noteful use?

When was Noteful last checked?

Documentation

noteful-mcp

Features

Quick start

How it works

Configuration

Tools

Study notes look

Examples for the agent

Copying a page design

Development

License

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Noteful?

Does Noteful need an API key?

What transport does Noteful use?

When was Noteful last checked?

Documentation

noteful-mcp

Features

Quick start

How it works

Configuration

Tools

Study notes look

Examples for the agent

Copying a page design

Development

License