notability-mcp

An MCP server for your Notability notes. It lets Claude, Cursor or any other MCP client search and read what you wrote, including handwriting.

Unofficial and not affiliated with Ginger Labs. Notability has no public API, so this reads your notes through the private API its web app uses, which can change without notice.

How it works

notability-mcp sync downloads your notes into a SQLite file on your computer and runs OCR on every handwritten page. Search is fuzzy, so "conjugate" still finds a page the OCR read as "conjogate". The text of PDFs your notes are written on, like lecture slides or past exams, is searchable too.

OCR is rough, especially on math, so the server can also return any page as an image: your ink drawn over its PDF page. A model that reads images, like Claude, can then read your handwriting directly.

The server itself only reads that local file. It never loads your Notability token and makes no network requests; sync is the only command that talks to Notability.

Requirements

• macOS, Windows or Linux
• uv
• A Notability account with your notes synced to it

Setup

1. Log in

uvx notability-mcp login

You'll be asked for your nb-auth-token, the cookie Notability's web app signs you in with. To copy it, sign in at notability.com/app, open your browser's developer tools, go to Application (Chrome, Edge) or Storage (Firefox, Safari), then Cookies > https://notability.com, and copy the value of nb-auth-token.

The token is saved in your system keychain: Keychain on macOS, Credential Manager on Windows, Secret Service on Linux.

2. Sync

uvx notability-mcp sync

The first sync downloads every note and its PDFs and runs OCR on each handwritten page. For 4,000 pages that takes about 10 minutes on a Mac and up to an hour on Windows or Linux, where OCR is slower. Later syncs only fetch notes that changed. Run it again whenever you want new notes to show up, or schedule it with cron, launchd or Task Scheduler.

3. Connect your client

Most clients take this config:

{
  "mcpServers": {
    "notability": {
      "command": "uvx",
      "args": ["notability-mcp", "serve"]
    }
  }
}

claude mcp add notability -s user -- uvx notability-mcp serve

uvx notability-mcp setup

code --add-mcp '{"name":"notability","command":"uvx","args":["notability-mcp","serve"]}'

codex mcp add notability -- uvx notability-mcp serve

Then ask something like:

• What did I write about struct allocation in CPSC 213?
• Summarize my MATH 300 notes from last week.
• Find the page where I worked out the harmonic conjugate and check my steps.

If you'd rather type notability-mcp than uvx notability-mcp, install it once with uv tool install notability-mcp.

Tools

All four are read-only.

Configuration

The index is stored in ~/Library/Application Support/notability-mcp on macOS, %LOCALAPPDATA%\notability-mcp on Windows and ~/.local/share/notability-mcp on Linux.

Limitations

• OCR is Apple's Vision framework on macOS and RapidOCR elsewhere. On 20 pages of handwritten math, Vision found 44% of the key words and 7% of the formulas; RapidOCR found 46% and 16%. Search will usually find the right page, but read the page image before trusting anything exact.
• Page images show ink and PDF pages. Shapes, pasted images and typed text aren't drawn yet.
• Notes other people shared with you aren't synced.
• Audio recordings aren't transcribed or searched.
• On Linux without a keyring (a headless server, say), login can't save the token. Set NOTABILITY_TOKEN instead.

Development

make install   # create .venv and install dependencies
make hooks     # pre-commit (ruff) and commit-msg (Conventional Commits) hooks
make check     # lint, typecheck, tests
make inspect   # open the server in MCP Inspector

Commits follow Conventional Commits.

Credits

The Notability wire format was reverse-engineered by notability-cli (MIT). See THIRD_PARTY_NOTICES.md.