An unofficial command-line client and MCP server for the Notability web app, written in Rust.
Unofficial. Not affiliated with, endorsed by, or sponsored by Notability or Ginger Labs, Inc. It talks to an undocumented private web API that can change or break at any time. See Limitations and Disclaimer.
It is:
- A single
notabilitybinary that reads and edits your own Notability library from a terminal: notes, folders, typed text, math, ink, shapes, comments, pages, imports, exports, recordings, sharing, Learn (summaries, quizzes, flashcards) and Notability AI chat. - An MCP server (stdio or HTTP) that exposes the same commands as tools, read-only by default.
- Scriptable: stable exit codes, JSON/YAML/TOON/Markdown/JSONL output, cursors for pagination, and dry-run previews for destructive actions.
It isn't:
- An official Notability product or a supported API client.
- A replacement for the Notability apps. Several features only exist on Notability's device apps (see Limitations).
- A sync or backup service. It makes requests only when you run a command.
- A way to access anyone else's notes. It uses your own signed-in session and nothing else.
Notability has no public API. Notes live in its own apps and web app, so they are hard to search
from a terminal, script, export in bulk, or hand to other tools. notability-cli speaks the
same web protocol as notability.com/app (GraphQL, a Socket.IO library feed and a FlatBuffers
note edit log), so you can work with your library from a shell, from scripts, or from any MCP
client.
131 commands under 9 nouns. docs/STATUS.md lists every command and whether
it has been verified end to end against the live API (74 have).
| Noun | What you can do |
|---|---|
notes |
List, filter, sort and paginate notes; get one note (metadata, pages, recordings, Learn status, or Markdown); search titles and text; build a local full-text index; create, rename, duplicate, move, favourite, switch paged/pageless; trash, restore, purge |
folders |
List folders as a list or tree; show display order; create, rename, edit colour/emoji/lock, move, reorder, delete (with --recursive); manage subjects and dividers |
content |
Show a note's decoded edit log; list and edit typed text (styles, paragraphs, checklists, code blocks, text boxes), LaTeX math blocks, ink strokes (draw, erase), shapes, images (crop, flip), comments (add, reply, edit, move, delete) and pages (add, delete, reorder, paper template); move a selection |
files |
Import PDFs, images, audio, .ntb bundles, YouTube transcripts, Office documents (converted locally with LibreOffice), PDFs by URL and Google Drive files; export to Markdown, text, JSON, transcript, .ntb, source PDF, assets or a locally rendered PDF; render a page to PNG; read the table of contents |
audio |
List and delete recordings; read transcripts (with timestamps); upload an audio file as a recording; record from this machine's microphone with ffmpeg and attach it, optionally transcribed; live transcription from the microphone or a file, streamed as you speak |
share |
Show link scope and collaborators; set link access; revoke the link; send email invitations; search people you can invite (business accounts); change or remove a collaborator; answer access requests |
learn |
Read AI summaries and study-material status; generate summaries, quizzes and flashcards; build quizzes from a PDF's table of contents; "Finish my notes" (an AI write-up of the note's text, PDFs and transcripts, inserted into the note); guided study sessions ("Start study session": memorize, practice, master); Brain Break discussions; syllabus import into a course folder; wait for generation; run quiz sessions; review and rate due flashcards; import flashcards from a delimited file; explain a question |
chat |
Ask Notability AI (optionally about a note); list, read and delete threads; see what context the assistant gets for a note; index recent notes for chat |
account |
Sign in, refresh, sign out and check the session; profile, quotas, feature flags, calendar events, settings; onboarding survey answers and use type; read-only raw GraphQL queries |
Notes can be referenced by id, an id prefix of at least 6 characters, an exact title, or
folder/path/title.
You need a Rust toolchain (1.92 or newer; rust-toolchain.toml pins it for rustup users).
ffmpeg is optional and only needed for audio record and for importing audio formats other than
m4a, mp4 and webm.
Install from Git:
cargo install --git https://github.com/Zpankz/notability-cli nb-cliOr build from source:
git clone https://github.com/Zpankz/notability-cli
cd notability-cli
cargo build --release
./target/release/notability --versionThe release binary is about 19 MB and starts in a few milliseconds. All dependencies come from crates.io.
Notability's web app keeps a single session token in an HttpOnly cookie called nb-auth-token.
The CLI never asks for your password and never takes the token as a command-line argument. There
are three ways to give it a session:
-
From a signed-in browser over CDP. Sign in at
https://notability.com/appin a Chromium-based browser started with remote debugging, then run:# e.g. chromium --remote-debugging-port=9222 notability account login --cdp http://127.0.0.1:9222The CLI connects to the browser's DevTools endpoint and calls
Storage.getCookiesonce to read thenb-auth-tokencookie. It does not open, attach to or script any page. The endpoint defaults to$NOTABILITY_CDP, orhttp://127.0.0.1:9222. -
From stdin, if you copied the cookie value yourself (for example from the browser's developer tools):
notability account login --token-stdin < token.txt -
From the environment:
NOTABILITY_TOKENoverrides any stored session and is never written to disk.
account login checks the token against the API before saving it. It is stored in
credentials.json inside $NOTABILITY_CONFIG_DIR, or $XDG_CONFIG_HOME/notability-cli, or
~/.config/notability-cli. The directory is created with mode 0700 and the file is written
with mode 0600. A random device id used by the note protocol is kept next to it in
settings.json.
notability account status # validates the session against the API
notability account status --offline # inspect the stored token without a request
notability account refresh # re-import the cookie from the browser
notability account logout # delete the stored credentialsThe token is shown redacted in all output.
notability --help # nouns
notability notes --help # commands under a noun
notability notes list --limit 20
notability notes search "roadmap" --format json
notability notes get "Projects/Kickoff" --format md
notability files export "Projects/Kickoff" --to md --to pdf --out ./export
notability content text add "Projects/Kickoff" "A new paragraph"
notability notes delete "Old draft" --yesOutput formats. --format toon|json|yaml|md|jsonl (TOON is the default).
--json prints the full {ok, data, meta} envelope. --filter-output a,b.c keeps only some keys,
and --token-limit / --token-offset page through large outputs. List commands return
meta.next_cursor; pass it back with --cursor.
Destructive commands (notes delete, folders delete, notes trash empty, …) ask for
confirmation in an interactive terminal and need --yes in scripts; without it they exit 2 with
CONFIRM_REQUIRED.
Shell completions:
eval "$(notability completions bash)" # or zsh, fish, nushellAgent skills and manifests. notability --llms prints a compact manifest of every command
(--llms-full for the full schemas), and notability <command> --schema prints one command's JSON
Schema. notability mcp add registers the MCP server with supported coding agents.
Skills. The repository ships one skill per noun plus a root notability skill in
skills/. Each says when to use it and walks the noun's subcommands with their key
flags and safety notes. notability skills add installs them (as notability,
notability-notes, notability-learn, …) for supported agents, and notability skills list
shows what would be installed. After changing a command or its help text, regenerate them with:
cargo run -p nb-cli -- skills generate --out skillscargo test fails if the committed files differ from the generated output.
Environment variables:
| Variable | Purpose |
|---|---|
NOTABILITY_TOKEN |
Session token (overrides stored credentials) |
NOTABILITY_CDP |
Default CDP endpoint for account login / refresh |
NOTABILITY_CONFIG_DIR |
Where credentials.json and settings.json live |
NOTABILITY_CACHE_DIR |
Local full-text index cache |
NOTABILITY_ALLOW_WRITES, NOTABILITY_ALLOW_AI |
Same as --allow-writes / --allow-ai for the MCP server |
NOTABILITY_API_BASE, NOTABILITY_COLLAB_BASE |
Override the API endpoints (testing) |
Every command is also an MCP tool, named after its path with _ (for example notes_list,
content_math_add). Three resources are exposed as well: notability://folders,
notability://notes/recent and notability://note/{note_id} (a note as Markdown).
stdio (the usual form for desktop MCP clients):
{
"mcpServers": {
"notability": {
"command": "notability",
"args": ["--mcp"]
}
}
}HTTP (streamable HTTP on /mcp):
notability --mcp --http 127.0.0.1:8765{
"mcpServers": {
"notability": { "url": "http://127.0.0.1:8765/mcp" }
}
}The HTTP server has no authentication of its own and acts with your Notability session, so bind
it to 127.0.0.1 only. Tools that use this machine's devices (audio recording) are hidden over
HTTP.
Progressive disclosure. By default the server lists only 8 tools: 4 meta tools
(search_tools, get_tool_details, call_read_tool, call_write_tool) and 4 starters
(account_me, notes_get, notes_list, notes_search). The client finds the rest with
search_tools. Pass --mcp-flat to list every reachable tool directly, or
--mcp-tools 'folders_*,notes_list' to restrict the set.
Gates. The server is read-only unless you opt in:
| Flags | Reachable tools |
|---|---|
| (none) | 43 read-only tools |
--allow-writes |
115 (adds create, edit, move, delete, import, sharing and profile changes) |
--allow-ai |
48 (adds AI reads that spend quota) |
--allow-writes --allow-ai |
125 (adds AI actions that write, such as learn_finish, learn_toc_quiz, learn_syllabus and audio_live_start) |
Local-only commands (account login, logout, refresh), the raw account graphql query and
share invite (which emails people) are never exposed over MCP.
Dry-run confirm. A destructive tool called without confirm: true does nothing and returns a
preview ({"dry_run": true, "command": …, "args": …}) so the client can check with you first.
Calling it again with confirm: true applies it.
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | generic error |
| 2 | usage: bad flag or value, unknown command, bad cursor, missing --yes |
| 3 | auth: not signed in or session expired |
| 4 | not found |
| 5 | rate limited |
| 6 | server error |
| 7 | quota exceeded |
| 8 | unsupported by the API |
| 9 | write rejected by the server |
More detail on envelopes and output is in docs/OUTPUT.md.
- Private, undocumented API. Notability does not publish or support this API. Everything here
is based on how the web app behaves today, and any web release can change or break it without
notice.
docs/PROTOCOL.mddescribes what is known. - Rate limiting. The client waits at least 250 ms between requests and retries transport
errors, HTTP 429 and 5xx with exponential backoff, honouring
Retry-After. Exit code 5 means the server is still rate limiting you. Please don't use it for bulk scraping. - Quotas. Transcription, Learn generation and AI chat spend the same quotas as the apps.
- Device-only features. Tables, tags, handwriting-to-text and handwritten math recognition exist only in Notability's device apps; the web API has nothing to call for them. Handwriting is available as vector ink, not text.
- Google Drive import needs your own Google OAuth access token (
drive.readonlyscope) inGOOGLE_DRIVE_TOKEN; the web app's Drive picker token can't be reused. - Office import needs LibreOffice (
soffice) on this machine; live transcription and microphone recording need ffmpeg. - Invitable-user search (
share search-users) only works for Notability business members. - Not run live: Brain Break (
learn discuss start|reply) andaccount survey-remove; seedocs/STATUS.md. - Rendered PDF export is a local approximation. The web app renders "Export as PDF" in the
browser;
files export --to pdfandfiles renderdraw source PDFs, paper, ink, shapes, images and typed text locally, with simplified text styling and pen textures.
This project is for educational and non-commercial personal use only. It is not affiliated with, endorsed by, or sponsored by Notability or Ginger Labs, Inc. Notability is a trademark of its owner. Use it at your own risk and in accordance with Notability's terms of service, and only to access your own account.
MIT. Copyright 2026 Zpankz.