Skip to main content
Glama
goodnotes-inkeye-mcp

goodnotes-inkeye-mcp

by oenderg

goodnotes-inkeye-mcp

An MCP stdio server for reading a live Goodnotes library. It exposes notebook metadata, page images rendered from the current strokes, exact typed text, and a clearly-labelled OCR/PDF text hint.

It is a thin transport over the gnreader distribution (gnstore, gnlive, gntext and gnreader). Nothing is uploaded; there are no network calls at runtime.

How it works

  1. gnstore copies the live RocksDB (notes_main.db), its WAL and the SQLite projection into a writable snapshot. The Goodnotes container is only read.

  2. gnlive loads the page's imported PDF/image background and decodes the live page records with gnreader.

  3. Strokes, text and f1 images are drawn in NotesZIndex order. Highlighters use a per-channel multiply and preserve ink; auto-straightened bars get round caps and compact scribbles are filled solid. Missing image attachments yield an image missing warning instead of a failed page. FillShapeItem is decoded but not drawn yet; it yields a fill shape warning.

  4. The PNG and a JSON sidecar are cached under $GNREADER_HOME or $GOODNOTES_INKEYE_HOME; the cache is capped and pruned.

Related MCP server: reMarkable MCP Server

Requirements

  • macOS with the Goodnotes application installed.

  • Python 3.10+.

  • The application that launches the MCP server needs Full Disk Access to read ~/Library/Containers/com.goodnotesapp.x.

  • A writable home for snapshots/cache. GNREADER_HOME defaults to ~/.cache/gnreader; GOODNOTES_INKEYE_HOME is also honored.

Install

From GitHub:

python -m venv ~/.local/share/goodnotes-inkeye/venv
~/.local/share/goodnotes-inkeye/venv/bin/pip install \
  "git+https://github.com/oenderg/goodnotes-inkeye-mcp.git"

The gnreader dependency is declared as gnreader @ git+https://github.com/oenderg/gnreader.git. For local development, install the local checkout first and then install this package with --no-deps:

python -m venv .venv
. .venv/bin/activate
pip install -e ../gnreader
pip install -e . --no-deps
pip install "mcp>=1.12,<2" pypdfium2 Pillow

Register with Claude

claude mcp add goodnotes-inkeye -s user -- \
  ~/.local/share/goodnotes-inkeye/venv/bin/goodnotes-inkeye-mcp

The console script starts the stdio server. The equivalent JSON is:

{
  "mcpServers": {
    "goodnotes-inkeye": {
      "command": "<venv>/bin/goodnotes-inkeye-mcp",
      "args": []
    }
  }
}

Use the real absolute path to the venv on your machine. Do not point the command at a checkout of the source tree unless the checkout is installed.

Tools

Tool

Returns

list_notebooks(folder='')

Folder path, UUID, live page count, modified date, source=live. Optional folder prefix.

find_notebooks(query)

Up to 50 notebooks matching all query words against folder/name/UUID.

get_notebook_info(notebook)

UUID, folder, live/deleted page counts, dates, page ids.

get_page_image(notebook, page, max_side=0)

[label, Image] PNG, 1-based live page, fresh snapshot.

get_pages(notebook, start, end, max_side)

Up to 8 PNG pages from one snapshot.

get_page_text(notebook, page)

Exact typed-text items from gntext plus a clearly-labelled unreliable OCR hint.

get_page_text_hint(notebook, page)

Cheap OCR/PDF text hint; explicitly unreliable.

server_status()

Snapshot age, library counts, package versions, capabilities, cache use.

Notebook arguments accept a document UUID, exact name, or unique name part. Ambiguous input returns a candidate list instead of guessing. Page numbers are 1-based over live (non-deleted) pages.

Privacy and safety

  • The Goodnotes container and backup folder are never modified.

  • Snapshots and render caches are the only writes; they live under the configured home (~/.cache/gnreader by default), never inside the package or the container.

  • That directory holds a copy of your Goodnotes database and rendered images of your notebook pages. Treat it like the notebooks themselves, and delete it to wipe the cache.

  • The server itself makes no network calls. Page images and text it returns are sent to whichever AI client you connect it to, under that client's privacy terms.

  • OCR is MyScript output and may be wrong, incomplete or stale. Use get_page_text for exact typed items and get_page_image to verify ink.

Known limits

The full list comes from gnreader.capabilities() and is printed by server_status().

  • No write support.

  • Legacy item kinds f3, f4 and f6 are unsupported.

  • Nexus/Yjs layout is approximate; math items are attachment/placeholder only.

  • Shape fill/stroke, sticky notes and elbow/hobby connectors are rendered for the calibrated item set. Sticker colour bodies, pattern tape and type-5 grainy pencil are also drawn; hobby uses a Hobby spline.

  • The live renderer does not draw fills yet (fill shape warning). Live f1 images are supported, including rotated images; missing/unreadable attachments warn as image missing.

  • Whiteboard notebooks have no page canvas and render blank.

  • Missing built-in/sticker backgrounds render white.

  • Eraser masks are decoded but not applied.

  • Highlighter straight bars now have round caps; compact freehand marks use a solid disc union. Freehand ends follow their stored path.

  • Cache entries are invalidated by package version and installed-renderer code fingerprint.

Updates

Upgrade the package in the server venv, then start a new Claude session so the MCP process restarts and loads the new code. A long-running server keeps the old modules in memory.

License

Licensed under the PolyForm Noncommercial License 1.0.0: you may use, modify and share it for noncommercial purposes. Commercial use needs a separate licence from the author.

Required Notice: Copyright (c) 2026 oenderg (https://github.com/oenderg)


Unaffiliated with Goodnotes Limited. "Goodnotes" is their trademark; it is used here only to describe compatibility.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers