GoodNotes MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GoodNotes MCP Server list my notebooks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GoodNotes MCP Server
An MCP (Model Context Protocol) server that reads handwritten notes from GoodNotes on macOS. It exposes your handwritten notebooks as structured data that AI assistants like Claude can read, search, and process.
How It Works
GoodNotes stores all data in local SQLite databases on macOS:
projection.sqlite— document metadata (names, folders, page ordering)fts.sqlite— full-text search index with OCR'd handwriting (multiple recognition candidates per word)
This MCP server reads those databases (read-only) and exposes 6 tools:
Tool | Description |
| List all notebooks with IDs, page counts, dates |
| Read OCR text from a notebook (supports page ranges) |
| Read OCR text from a single page |
| Full-text search across all handwritten notes |
| Find new/changed pages since last processing |
| Mark pages as processed (for pipeline workflows) |
OCR Candidate Format
GoodNotes OCR produces multiple word candidates. The server returns them separated by |:
Temple|Tomple|temple Voice|Voica recognitionYour AI assistant picks the best word using semantic context — much more accurate than taking the top candidate alone.
Related MCP server: reMarkable MCP Server
Requirements
macOS (GoodNotes stores its databases locally)
GoodNotes installed and synced
Python 3.11+
uv (recommended) or pip
Installation
git clone https://github.com/withsivram/goodnotes-mcp.git
cd goodnotes-mcp
uv venv && uv pip install -e .Configuration
Claude Code
Add to your Claude Code MCP settings:
{
"mcpServers": {
"goodnotes": {
"type": "stdio",
"command": "/path/to/goodnotes-mcp/.venv/bin/python",
"args": ["/path/to/goodnotes-mcp/server.py"]
}
}
}Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"goodnotes": {
"command": "/path/to/goodnotes-mcp/.venv/bin/python",
"args": ["/path/to/goodnotes-mcp/server.py"]
}
}
}Environment Variables
Variable | Default | Description |
|
| Path to GoodNotes SQLite databases |
|
| Path to processing state file |
Usage
Once configured, your AI assistant can:
List your notebooks: "What notebooks do I have in GoodNotes?"
Read notes: "Read my latest notebook"
Search: "Search my handwritten notes for 'meeting action items'"
Process pipeline: Use
get_unprocessed+mark_processedto build automated workflows (e.g., handwriting → structured Obsidian notes)
Example: Processing Notes into Obsidian
The server is designed as a minimal data pipe — all intelligence (OCR resolution, categorization, structuring) happens in the AI assistant. A typical workflow:
get_unprocessed→ find new pagesread_notebook→ get raw OCR with word candidatesAI resolves
Temple|Tomple|temple→ "Temple" using contextAI categorizes and structures into markdown
Write to Obsidian (or any markdown-based system)
mark_processed→ track what's been handled
Architecture
iPad (GoodNotes) → iCloud Sync → macOS SQLite DBs → MCP Server → AI AssistantThe server is intentionally minimal (~390 lines, zero external dependencies beyond mcp). All intelligence lives in the AI layer, making the server easy to maintain and extend.
License
MIT License — see LICENSE.
Available Tools
6 toolsget_unprocessedA
Get notebooks and pages that haven't been processed yet or changed since last processing.
Compares the tracking file against current FTS index to find new/changed content.
Inputs: no named parameters. Returns: result
list_notebooksA
List all GoodNotes notebooks with their names, IDs, page counts, and last modified dates.
Filters out templates (documents with epoch-zero timestamps). Returns a formatted list of user notebooks sorted by last modified date.
Inputs: no named parameters. Returns: result
mark_processedA
Mark pages as processed after they've been written to Obsidian.
Args: notebook_id: The document UUID page_ids: Comma-separated page UUIDs to mark as processed
Inputs: page_ids (required), notebook_id (required). Returns: result
read_notebookA
Read OCR text from a GoodNotes notebook.
Returns the handwriting-recognized text for each page, with multiple word candidates separated by | so Claude can pick the best word from context.
Args: notebook_id: The document UUID from list_notebooks page_start: First page to read (1-indexed, default: 1) page_end: Last page to read (0 = all pages, default: 0)
Inputs: notebook_id (required), page_end, page_start. Returns: result
read_pageA
Read OCR text from a single page of a GoodNotes notebook.
Args: notebook_id: The document UUID page_number: Page number (1-indexed)
Inputs: notebook_id (required), page_number (required). Returns: result
search_notesA
Search across all handwritten notes using case-insensitive text search.
Splits multi-word queries so each word is matched independently — necessary because GoodNotes OCR stores words in separate groups delimited by special chars.
Args: query: Search term (each word matched independently, case-insensitive)
Inputs: query (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
read_notebook and read_page overlap significantly, as read_notebook can read a single page using page_start/page_end, causing potential misselection. The other tools (list, get_unprocessed, search, mark_processed) are clearly distinct.
Tool names follow a snake_case verb_noun pattern, but verbs vary (list, read, get, search, mark) and 'get_unprocessed' and 'mark_processed' use adjectives rather than clear nouns, creating minor inconsistency.
With 6 tools, the set is well-scoped for the server's purpose of reading, searching, and tracking GoodNotes content. It is neither too sparse nor overly heavy.
The core workflow of listing notebooks, reading pages, searching, retrieving unprocessed pages, and marking them processed is covered. Minor gaps include redundancy between read_notebook/read_page and no explicit tool for listing page IDs independently.
Maintenance
Related MCP Connectors
Read and search your handwritten Boox notes from Claude or ChatGPT. Needs a Margen account.
Read and write the notes and folders of your Grape account, the AI note-taking app.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to read, search, and traverse your reMarkable tablet's library, including handwritten notes via OCR.12MIT
- AlicenseAqualityAmaintenanceEnables AI assistants to read, search, and traverse your entire reMarkable library, including handwritten notes via OCR.14265MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to read, search, and traverse your reMarkable tablet library, including handwritten notes via OCR, turning it into a second brain.1722MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to search and edit Apple Notes on macOS using semantic search, with safe write operations and full local indexing.121MIT