apple-books-mcp
Summary: An MCP server that gives Claude read access to your Apple Books library — books, collections, highlights, notes, reading progress and the text of non-DRM EPUBs — plus opt-in collection editing.
Browse and search books — list all books, search by title or author (ignoring case, accents and quote/dash style), search titles only, filter by genre, and describe a book (metadata, progress, annotation count, whether its text is readable, and an "Open in Books" link).
Track reading status — books in progress, finished, unstarted, and most recently read.
Explore highlights and notes — list all annotations or a single book's annotations in reading order, recent annotations, describe one annotation, get the passage around a highlight with it marked in
«...», filter highlights by color, search your notes, search across all annotation fields, and query by date range.Read book text (non-DRM EPUBs downloaded to this Mac) — list a book's table of contents, fetch chapter content (paginated, including the chapter you're currently reading via
chapter_id="current"), and get your current reading position.Manage collections — list, describe, search by title, and list a collection's books; with
--enable-writes, also create, rename and delete collections and add or remove books (auto-backup, refuses while Books is open).Library stats — a summary of the library with reading stats.
Resource —
apple-books://currently-readingattaches a pointer to the book you're reading now (progress, current chapter, highlight count, open link).Prompts —
weekly_digest,library_snapshotandrevisit_bookone-click workflows.
Provides tools for interacting with Apple Books, allowing access to book collections, detailed book information, and annotation management including highlights and notes.
Provides support for the developer through donation links to Buy Me A Coffee platform.
Facilitates contribution to the project through the GitHub repository, including issue reporting and pull request submission.
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., "@apple-books-mcp what are my recent highlights from 'Dune'?"
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.
Apple Books MCP
Model Context Protocol (MCP) server for Apple Books.
At a glance
Pick up where you left off — Claude sees the book you're reading, your progress and the chapter you're on, and pulls that chapter's text (
chapter_id="current") and your highlights when it needs them.Find any book — by title or author, ignoring case, accents and curly quotes, with a link that opens it in Apple Books.
Expand on any highlight — get the surrounding paragraph explained in context, with the exact anchor you marked shown in
«...».Revisit a book — pull your highlights, cluster them by theme, and quote you back to yourself.
Reflect on your reading — patterns across books, recurring ideas in your highlights, what you're actually drawn to.
https://github.com/user-attachments/assets/77a5a29b-bfd7-4275-a4af-8d6c51a4527e
And much more!
Related MCP server: Co-Reading MCP
Available Tools
List and search tools return one page at a time: 50 annotations or 200 books by default, limit between 1 and 500, and offset for the next page. When there is more, the output says so and names the next offset.
How results work:
Ids are integers: every row starts with one, as in
[175] Title by Author, to pass on asbook_id,annotation_idorcollection_id. A numeric string such as"175"is accepted too;true,falseand fractions are not ids.A failure (an unknown id, a book that isn't downloaded, a bad
color) comes back as an MCP error (isError) whose message names what to do next, often another tool to call. An empty result ("No books matched …") is a normal answer, not an error.Text taken from your books (chapter text, the passage around a highlight, a table of contents, a book's description) is wrapped in
<book_text>…</book_text>. The server's instructions tell Claude that this text is untrusted data from the book, never instructions to follow.Highlights from books you've removed from the library are kept by Apple Books. They are shown per removed book, as "Removed book (asset 3F2A1B2C…)", after the books still in your library.
Collections
Tool | Description | Parameters |
list_all_collections | List all collections | limit?: int (default: 200), offset?: int |
get_collection_books | Get all books in a collection | collection_id: int |
describe_collection | Get details of a collection | collection_id: int |
search_collections_by_title | Search for collections by title | title: str |
Editing collections (opt-in)
Off by default. Enable by adding --enable-writes to the server args:
"args": ["apple-books-mcp", "--enable-writes"]With the Claude Desktop extension, turn on Allow editing collections in the extension's settings instead.
Apple provides no automation API for collections, so these write directly to the library database — behind guard rails: every write refuses while Books is open, takes an automatic WAL-safe backup first (~/.py_apple_books/backups/), validates the schema and aborts on drift, and only touches user-created collections (plus "Want to Read" membership). Deleting a collection never deletes the books in it.
⚠️ If iCloud sync for collections is enabled, direct edits may not propagate to other devices and can be reverted by a cloud re-sync.
Tool | Description | Parameters |
create_collection | Create a new collection | title: str, details?: str |
rename_collection | Rename a user-created collection | collection_id: int, new_title: str |
delete_collection | Delete a user-created collection (books untouched) | collection_id: int |
add_book_to_collection | Add a book to a collection (idempotent) | collection_id: int, book_id: int |
remove_book_from_collection | Remove a book from a collection (idempotent) | collection_id: int, book_id: int |
Books
Tool | Description | Parameters |
list_all_books | List all books | limit?: int (default: 200), offset?: int |
search_books | Find books whose title or author contains the query, ignoring case, accents and quote/dash style | query: str, limit?: int (default: 200), offset?: int |
search_books_by_title | Search for books by title (same matching, titles only) | title: str, limit?: int (default: 200), offset?: int |
describe_book | Get details of a particular book (metadata, progress, annotation count, description), whether its text is readable (see below) and an "Open in Books" link | book_id: int |
list_annotations | Annotations for a book in reading order (id + text + chapter per row, with your notes) | book_id: int, limit?: int (default: 50), offset?: int |
get_books_by_genre | Get books by genre (substring match) | genre: str, limit?: int (default: 200), offset?: int |
describe_book has a Readable text line saying whether the chapter tools can read the book, and if not why: yes (EPUB), a PDF, DRM-protected, not downloaded (in iCloud only, an Apple Books Store title, or never downloaded) or a missing file. It is worked out from the library's records and file metadata, without opening the book: reading a file that is only in iCloud would make macOS download it.
Open in Books links (ibooks://assetid/…) open the book in Apple Books. They appear in describe_book, describe_annotation, get_current_reading_position and the Currently Reading resource.
Reading Status
Tool | Description | Parameters |
get_books_in_progress | Get books currently being read | limit?: int (default: 200), offset?: int |
get_finished_books | Get books that have been finished | limit?: int (default: 200), offset?: int |
get_unstarted_books | Get books not yet started | limit?: int (default: 200), offset?: int |
get_recently_read_books | Get the most recently read books | limit?: int (default: 10), offset?: int |
Annotations
Tool | Description | Parameters |
list_all_annotations | Browse every annotation grouped by book, newest first, with your notes | limit?: int (default: 50), offset?: int |
recent_annotations | Get most recent annotations (flat, with date + book per row) | limit?: int (default: 10), offset?: int |
describe_annotation | Get full details of a single annotation, with the book's "Open in Books" link | annotation_id: int |
get_annotation_context | Text window around a highlight (the paragraph it's in), with the highlight marked | annotation_id: int, chars_before?: int (default: 500), chars_after?: int (default: 500) |
get_highlights_by_color | Highlights of a particular color, grouped by book | color: yellow|green|blue|pink|purple, limit?: int (default: 50), offset?: int, order_by?: newest|oldest |
search_notes | Search user notes (shows highlight + note inline) | note: str, limit?: int (default: 50), offset?: int, order_by?: newest|oldest |
search_annotations | Search across highlights + notes + surrounding text (shows notes inline) | text: str, limit?: int (default: 50), offset?: int, order_by?: newest|oldest |
get_annotations_by_date_range | Annotations within a date range, inclusive of the | after?: YYYY-MM-DD, before?: YYYY-MM-DD, limit?: int (default: 50), offset?: int, order_by?: newest|oldest |
Library Stats
Tool | Description | Parameters |
get_library_stats | Get library summary with reading stats | None |
Book Content
Only works for non-DRM EPUBs downloaded to this Mac (imported books, Project Gutenberg, Standard Ebooks, etc.). Apple Books Store purchases are usually FairPlay-protected and return a clear error, and iCloud-only books a "not downloaded" hint; describe_book's "Readable text" line tells in advance.
Tool | Description | Parameters |
list_book_chapters | Table of contents for a book (chapter titles, order, nesting) | book_id: int |
get_chapter_content | Plain-text content of a chapter, with optional | book_id: int, chapter_id?: str (default: "current"), offset?: int, max_chars?: int |
get_current_reading_position | The chapter the user last left off reading (via Apple Books' auto-bookmark CFI), with an "Open in Books" link | book_id: int |
Available Resources
Attachable data objects accessible from Claude Desktop's resource picker.
Resource | URI | Description |
Currently Reading |
| A short pointer to the book you're reading right now (the most recently opened in-progress book): title, author, book id, progress, an "Open in Books" link, the chapter you left off on with its chapter id (for non-DRM EPUBs; otherwise why its text can't be read), and how many highlights you have in it. It carries no chapter text or highlights; Claude fetches those on demand with |
Available Prompts
One-click workflows, accessible from Claude Desktop's prompt picker.
Prompt | Description | Arguments |
weekly_digest | Summarize what I've read and highlighted in the past week | days?: int (default: 7) |
library_snapshot | A reflection on my whole reading life | None |
revisit_book | Revisit your notes and highlights from a specific book | book_title: str |
Installation
Requirements
macOS, with Apple Books opened at least once (it creates the library the server reads).
Python 3.10 or newer. uvx and the Claude Desktop extension provide one if needed.
Installed with the server:
mcp>= 1.12 (< 2) andpy-apple-books>= 1.10 (< 2).
Using uv (recommended)
uvx runs apple-books-mcp without a separate install step.
brew install uv # for macos
uvx apple-books-mcp --versionThe first run downloads about 14 MB of dependencies and can take up to a minute, which is close to how long Claude waits for a server to start. Running the command above once in Terminal warms uv's cache before you add the server to Claude. --version prints the apple-books-mcp, mcp and py-apple-books versions uvx resolved.
Then add the server to Claude with the JSON config or the Claude Code command below.
Claude Desktop extension (.mcpb)
Claude Desktop can also install apple-books-mcp as an extension, without editing its config: download apple-books-mcp-<version>.mcpb from the latest GitHub release, double-click it (or open Settings → Extensions → Install Extension… and pick the file), and click Install. Desktop installs uv and the locked dependencies itself. Allow editing collections in the extension's settings does the same as --enable-writes.
On organization-managed Claude (Team/Enterprise), admins can limit Desktop Extensions to an allowlist or turn them off. If the .mcpb install is refused, use the JSON config below. If user-added MCP servers are also disabled by policy, ask your admin to approve the extension.
Using pip
Needs Python 3.10 or newer (the python3 that ships with macOS is 3.9). Install into a virtual environment:
python3 -m venv ~/.venvs/apple-books-mcp
~/.venvs/apple-books-mcp/bin/pip install apple-books-mcp
~/.venvs/apple-books-mcp/bin/apple-books-mcp --versionUpgrade later with ~/.venvs/apple-books-mcp/bin/pip install -U apple-books-mcp.
Using Docker (deprecated)
⚠️ The Docker image is deprecated and only partly works: a Linux container can't be granted the macOS permission, can't reach book files stored in iCloud Drive (so the tools that read book text fail), and can't tell whether Books is running (so collection writes are unsupported). Use uvx instead.
It can still serve library metadata and annotations. Mount the Apple Books container read-only and keep stdin open with -i. The image runs as an unprivileged user and reads the library from the same mount path as before:
docker run -i --rm -v ~/Library/Containers/com.apple.iBooksX/Data/Documents:/root/Library/Containers/com.apple.iBooksX/Data/Documents:ro ghcr.io/vgnshiyer/apple-books-mcp:latestIn a Claude config, spell out your home directory: Claude doesn't expand ~.
{
"mcpServers": {
"apple-books-mcp": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/Users/YOU/Library/Containers/com.apple.iBooksX/Data/Documents:/root/Library/Containers/com.apple.iBooksX/Data/Documents:ro",
"ghcr.io/vgnshiyer/apple-books-mcp:latest"
]
}
}
}First-run permission prompt (macOS)
The first time the server reads your library, macOS asks whether the program that started it may "access data from other apps", because Apple Books keeps its library in its own app container (~/Library/Containers/com.apple.iBooksX/). Click Allow.

macOS asks about the program Claude launches, not about apple-books-mcp itself:
uvxwith the recommended Claude Desktop config (the prompt above);the Python interpreter with the pip config;
claudewhen the server is configured in Claude Code;your terminal app when you run the server by hand.
The permission belongs to that program, so anything else it launches can use it too. apple-books-mcp only reads the library, plus the book files for chapter text; it changes nothing unless you pass --enable-writes.
To check, run uvx apple-books-mcp --doctor in Terminal: it reports whether the program running it may read the library and, if not, how to fix it. Run that way it checks your terminal app's permission, which macOS asks about separately from uvx or Claude.
Asked again after an update? Homebrew's uv/uvx and Homebrew or uv-managed Python builds aren't signed by a registered developer, so after brew upgrade uv (or a Python upgrade) macOS treats them as a new program and asks again. Click Allow.
Clicked "Don't Allow"? Tools then fail with "macOS denied access to the Apple Books library". (Older releases failed at startup instead, with "No sqlite files found in … Please open Apple Books at least once".) This permission has no switch in System Settings. To be asked again, run:
tccutil reset SystemPolicyAppDataThis clears the "data from other apps" decisions for all apps. Then quit and reopen Claude, and click Allow. Adding the program (e.g. /opt/homebrew/bin/uvx) to Full Disk Access in System Settings > Privacy & Security also works, but grants far more access.
Configuration
Claude Desktop Setup
Quit Claude Desktop (Cmd+Q) before editing ~/Library/Application Support/Claude/claude_desktop_config.json: Desktop rewrites the file while it runs, so edits made while it's open can be lost.
Using uvx (recommended)
{
"mcpServers": {
"apple-books-mcp": {
"command": "uvx",
"args": [ "apple-books-mcp" ]
}
}
}Plain apple-books-mcp still picks up new releases: uv checks PyPI for a newer version whenever its cached copy of the package index is more than 10 minutes old, which is usually the case when Claude starts. apple-books-mcp@latest gains nothing over that and makes uv build a fresh environment on every launch (3–12 s instead of about 1 s).
Faster or offline startup
Because uvx checks PyPI at launch, the server won't start while PyPI is unreachable. To avoid that:
Run
uv tool install apple-books-mcponce. The same uvx config then uses the installed copy and starts in about a second without contacting PyPI. Installed copies don't update themselves: runuv tool upgrade apple-books-mcpto get new releases.Or use
"args": ["--offline", "apple-books-mcp"]to run whatever version uv has already cached (after at least one online run), without any network access.
Using pip
Point Claude at the script inside the virtual environment from Using pip, with your home directory spelled out:
{
"mcpServers": {
"apple-books-mcp": {
"command": "/Users/YOU/.venvs/apple-books-mcp/bin/apple-books-mcp"
}
}
}Claude Code Setup
Claude Code doesn't read the Claude Desktop config. Add the server with:
claude mcp add --scope user apple-books-mcp -- uvx apple-books-mcpand check it with /mcp.
Environment variables
Set these in the server's "env" in the Claude config (e.g. "env": {"APPLE_BOOKS_MCP_THREADS": "4"} next to "args"), or with claude mcp add -e NAME=value.
Variable | Default | What it does |
| off |
|
|
| How many tool calls run at once. |
| Apple Books' own folder | The Apple Books |
|
| Seconds a library query may run before it is stopped; |
Troubleshooting
Where to look
uvx apple-books-mcp --doctorin Terminal checks the versions, finds the library, explains macOS permission problems and prints counts of what it read. It only reads, and never prints titles or text.~/Library/Logs/Claude/mcp-server-apple-books-mcp.log(named after yourmcpServerskey) has the server's own output, including Python tracebacks. For more detail, add"-v"to the args: the server then logs its version, the mcp and py-apple-books versions it runs with, and each request.~/Library/Logs/Claude/mcp.loglists failures. Its "Server started and connected successfully" line only means the process was launched, not that it works.~/Library/Logs/Claude/main.logrecords "Connected to apple-books-mcp (N tools)" when a Claude Code or Cowork session in Desktop loaded the tools.uvx apple-books-mcp --versionin Terminal shows which versions uvx resolves.
Common problems
"Connection closed", "Server disconnected" or "Server transport closed unexpectedly": the server exited at startup. Read the last error in the traceback in
mcp-server-apple-books-mcp.log.No module named 'mcp.server.fastmcp': uv picked an apple-books-mcp release older than 0.8.1 together with mcp 2.x, which removed the API those releases were built on (on Python 3.12 and older, uvx could even fall back to 0.1.2). 0.8.1 and newer work with Python 3.10+ and stay on mcp 1.x. Runuv cache clean apple-books-mcp, check thatuvx apple-books-mcp --versionreports 0.8.1 or newer, then quit and reopen Claude.A
No module named 'server'error in front of the real one is noise from releases before 0.8.4.
"Not ready after 60 seconds" or "Request timed out" at startup: the first launch was still downloading and installing dependencies. Run
uvx apple-books-mcp --versiononce in Terminal, then reopen Claude."macOS denied access to the Apple Books library" (older releases: "No sqlite files found in …"): see First-run permission prompt.
"No Apple Books library store found": Apple Books hasn't created its library for this macOS user yet. Open Books once, then try again.
Stopping a response while a tool runs: since 0.9 a stopped tool call is answered immediately and the server keeps serving other sessions; the call's remaining work finishes in the background (a write that had already started still completes; one that hadn't started never runs).
"Extension apple-books-mcp not found in installed extensions" in
main.logis harmless.
Getting Claude to retry
Claude Desktop chats: quit Claude completely (Cmd+Q) and reopen it. A server that failed to start isn't retried otherwise.
Claude Code and Cowork sessions in Desktop: start a new session; each new session retries the server.
Claude Code: run
/mcpand reconnect apple-books-mcp, or restart Claude Code.
Upcoming Features
Highlight export: a book's highlights and notes in reading order, with chapter headings
Fewer, broader tools in 1.0, where today several overlap
Titles for removed books, where Apple Books' caches still hold them
PDF content access (currently EPUB-only)
Contribution
Thank you for considering contributing to this project!
Development
Clone the repository and let uv create the virtual environment and install the package with its dependencies:
uv sync
uv run apple-books-mcp --version
uv run pytestTo build the Claude Desktop extension locally, install the pinned packer, then build:
npm ci --ignore-scripts --prefix mcpb
uv run python scripts/build_mcpb.pyThis writes dist/apple-books-mcp-<version>.mcpb and the registry's dist/server.json (--out DIR picks another folder). python scripts/build_mcpb.py --smoke dist/apple-books-mcp-<version>.mcpb installs the bundle the way Claude Desktop does and checks the server it starts.
Maintainers: publishing a GitHub release runs the release workflow, which checks the tag against every version field, publishes to PyPI, attaches the .mcpb to the release and publishes to the MCP Registry.
Debugging
Logs go to stderr, which Claude Desktop writes to ~/Library/Logs/Claude/mcp-server-<name>.log. Without flags the server logs only warnings and errors; -v adds startup details (versions, whether writes are enabled) and a line per request; -vv adds debug output from the MCP SDK.
With Claude Desktop
{
"mcpServers": {
"apple-books-mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/apple-books-mcp/",
"run",
"apple-books-mcp",
"-v"
]
}
}
}With inspector
npx @modelcontextprotocol/inspector uv --directory /path/to/apple-books-mcp run apple-books-mcpOpening Issues
If you encounter a bug, have a feature request, or want to discuss something related to the project, please open an issue on the GitHub repository. When opening an issue, please provide:
Bug Reports: Describe the issue in detail. Include steps to reproduce the bug if possible, along with any error messages or screenshots.
Feature Requests: Clearly explain the new feature you'd like to see added to the project. Provide context on why this feature would be beneficial.
General Discussions: Feel free to start discussions on broader topics related to the project.
Contributing
1️⃣ Fork the GitHub repository https://github.com/vgnshiyer/apple-books-mcp
2️⃣ Create a new branch for your changes (git checkout -b feature/my-new-feature).
3️⃣ Make your changes and test them thoroughly.
4️⃣ Push your changes and open a Pull Request to main.
Please provide a clear title and description of your changes.
License
Apple Books MCP is licensed under the Apache 2.0 license. See the LICENSE file for details.
Available Tools
31 toolsadd_book_to_collectionAdd a book to a collectionCIdempotent
Add a book to a collection (user-created collections and "Want to Read"). Idempotent. Requires write access and Books to be quit.
Args: collection_id: The collection's numeric ID. book_id: The book's numeric ID.
Inputs: book_id (required), collection_id (required).
create_collectionCreate a collectionA
Create a new collection in the user's Apple Books library. Requires write access and Books to be quit; a backup is taken automatically.
Args: title: Name for the new collection. details: Optional description.
Inputs: title (required), details.
delete_collectionDelete a collectionADestructiveIdempotent
Delete a user-created collection (built-in collections are refused). The books inside are NOT deleted — only the collection. Requires write access and Books to be quit.
Args: collection_id: The collection's numeric ID.
Inputs: collection_id (required).
describe_annotationDescribe an annotationARead-only
Describe a specific annotation in detail — text, note, book (with
an Open in Books: link), chapter, color, creation date. For the
passage around the highlight, call get_annotation_context
instead.
Args: annotation_id: The annotation's numeric ID.
Inputs: annotation_id (required).
describe_bookDescribe a bookARead-only
Describe a specific book in detail — metadata (title, author, genre,
page count), reading status (progress, last opened, finished date),
and annotation count. Also whether the chapter tools can read its
text (Readable text:, and why not), and an Open in Books:
link (ibooks://assetid/...) that opens it in Apple Books.
Args: book_id: The book's numeric ID.
Inputs: book_id (required).
describe_collectionDescribe a collectionBRead-only
Describe a specific collection in detail — title, details text, and the books contained in it.
Args: collection_id: The collection's numeric ID.
Inputs: collection_id (required).
get_annotation_contextGet the passage around a highlightARead-only
Return the passage around a specific highlight — the text before
and after, with the highlight itself wrapped in «...». Use
this to expand on a highlight without fetching the whole chapter.
Works for non-DRM EPUBs downloaded to this Mac; fails with a clear message for DRM-protected books, iCloud-only books, or older annotations that lack the chapter hint.
Args: annotation_id: The annotation's numeric ID. chars_before: Chars of context before the highlight (0–5000). Default 500. chars_after: Chars of context after the highlight (0–5000). Default 500.
Inputs: annotation_id (required), chars_after, chars_before.
get_annotations_by_date_rangeAnnotations by date rangeARead-only
Annotations created within a date range, newest first by default. Flat rows with the creation time and book name inline. Dates and times are in the Mac's local time zone, named in the header.
Row format::
YYYY-MM-DD HH:MM [id] text — chapter · Book TitleArgs:
after: Only include annotations created on or after this date
(YYYY-MM-DD, or YYYY-MM-DDTHH:MM).
before: Only include annotations created on or before this
date (YYYY-MM-DD covers the whole day, or YYYY-MM-DDTHH:MM).
limit: Max annotations to return (1–500, default 50).
offset: Annotations to skip, for paging.
order_by: newest (default) or oldest first.
Inputs: after, limit, before, offset, +1 more.
get_books_by_genreFind books by genreARead-only
Get books whose genre matches the given string (substring match).
Output is one row per match: [id] title by author (genre).
Args: genre: The genre to search for (e.g. "Romance", "Philosophy"). limit: Max books to return (1–500, default 200). offset: Books to skip, for paging.
Inputs: genre (required), limit, offset.
get_books_in_progressBooks in progressARead-only
Get books currently being read (progress > 0% and < 100%). Output
per row: [id] title by author with a progress summary below.
Args: limit: Max books to return (1–500, default 200). offset: Books to skip, for paging.
Inputs: limit, offset.
get_chapter_contentGet chapter textARead-only
Return the plain-text content of a chapter, paginated by default
to protect the context window. Get chapter_id from
list_book_chapters or from the (ch=...) suffix on
annotation listing rows, or pass "current" (the default) for
the chapter the user is reading in Apple Books. Works for non-DRM
EPUBs downloaded to this Mac.
Default max_chars=10000 (~2500 words) fits most chapters in
one call. Longer chapters return a slice with a footer naming
the exact offset to pass next. At most 50000 chars are
returned per call.
Every response ends with a footer like one of::
(full chapter returned: 4,872 chars.)
…(returned chars 0–10000 of 24,311 [10000 chars]. Call again with
offset=10000 to continue; 14,311 chars remaining.)
(returned chars 20000–24311 of 24311 [4311 chars]. End of chapter.)Args:
book_id: The book's numeric ID.
chapter_id: Chapter identifier, the 1-based chapter order as a
string (e.g. "5"), or "current" (the default): the
chapter of the user's reading position. A chapter whose id
is literally "current" wins.
offset: Character offset to start from. Defaults to 0.
max_chars: Max chars to return (1–50000). Default 10000.
Inputs: book_id (required), offset, max_chars, chapter_id.
get_collection_booksList a collection's booksARead-only
List the books in a collection as lean rows: [id] title by author. Descriptions are intentionally omitted — collections
with many books would otherwise emit tens of thousands of chars of
marketing blurb. Use describe_book(id) for details on any
specific book.
Args: collection_id: The collection's numeric ID.
Inputs: collection_id (required).
get_current_reading_positionCurrent reading positionARead-only
Return where the user last left off reading a book — chapter
title and chapter_id, no text — and an Open in Books: link to
the book. Follow up with get_chapter_content for the text.
Works for non-DRM EPUBs downloaded to this Mac. If Apple Books hasn't recorded a position, falls back to inferring from the user's most recent highlight (labeled as such in the output).
Args: book_id: The book's numeric ID.
Inputs: book_id (required).
get_finished_booksFinished booksARead-only
Get books that have been finished. Output per row: [id] title by author with a progress summary below.
Args: limit: Max books to return (1–500, default 200). offset: Books to skip, for paging.
Inputs: limit, offset.
get_highlights_by_colorHighlights by colorARead-only
Browse highlights of a particular color, grouped by book.
Output is one row per highlight: [id] text — chapter. The
book's name is shown once in the header, with a count of matching
highlights on this page.
Args:
color: yellow, green, blue, pink, or purple.
limit: Max annotations to return (1–500, default 50).
offset: Annotations to skip, for paging.
order_by: newest (default) or oldest first.
Inputs: color (required), limit, offset, order_by.
get_library_statsLibrary statsARead-only
Get a summary of your Apple Books library with reading stats.
Inputs: no named parameters.
get_recently_read_booksRecently read booksARead-only
Get the most recently read books, newest first (by when each was
last opened or read, whichever is later).
Output per row: [id] title by author with a progress summary
below.
Args: limit: Max books to return (1–500, default 10). offset: Books to skip, for paging.
Inputs: limit, offset.
get_unstarted_booksUnstarted booksARead-only
Get books that haven't been started yet (0% progress). Output per
row: [id] title by author with a progress summary below.
Args: limit: Max books to return (1–500, default 200). offset: Books to skip, for paging.
Inputs: limit, offset.
list_all_annotationsList all annotationsARead-only
Browse all annotations grouped by book, most recent first. Rows:
[annotation_id] <text> — <chapter title> (ch=<id>), with the
user's note, if any, on a second line prefixed with ↳ note:.
Pass ch=<id> to get_chapter_content for the chapter, or
call get_annotation_context(annotation_id) for the passage
around a specific highlight.
Args: limit: Max annotations to return (1–500, default 50). offset: Annotations to skip, for paging; a footer names the next offset when there are more.
Inputs: limit, offset.
list_all_booksList all booksARead-only
List all books in my Apple Books library. Output is one row per
book: [id] title by author. Use describe_book(id) for
details on any book.
Args: limit: Max books to return (1–500, default 200). offset: Books to skip, for paging; a footer names the next offset when there are more.
Inputs: limit, offset.
list_all_collectionsList collectionsARead-only
List all collections in my Apple Books library. Output is one row
per collection: [id] title. Use describe_collection(id) for
details or get_collection_books(id) to list its books.
Args: limit: Max collections to return (1–500, default 200). offset: Collections to skip, for paging.
Inputs: limit, offset.
list_annotationsList a book's annotationsARead-only
List annotations within a specific book in reading order (their
position in the book). Rows are lean —
[annotation_id] <text> — <chapter> (ch=<id>) — with the user's
note, if any, on a second line prefixed with ↳ note:.
Args: book_id: The book's numeric ID. limit: Max annotations to return (1–500, default 50). offset: Annotations to skip, for paging; a footer names the next offset when there are more.
Inputs: book_id (required), limit, offset.
list_book_chaptersList a book's chaptersARead-only
List the table of contents for a book — chapter titles, order, and nesting depth. Only works for non-DRM EPUBs that have been downloaded to this Mac.
Args:
book_id: The book's numeric ID (from list_all_books or similar).
Inputs: book_id (required).
recent_annotationsRecent annotationsARead-only
Most recent annotations, newest first. Flat rows with the creation time (the server's local time zone) and book name inline so Claude can see chronology across books at a glance.
Row format::
YYYY-MM-DD HH:MM [id] text — chapter · Book TitleArgs: limit: Max annotations to return (1–500, default 10). offset: Annotations to skip, for paging.
Inputs: limit, offset.
remove_book_from_collectionRemove a book from a collectionADestructiveIdempotent
Remove a book from a collection (the book stays in the library). Idempotent. Requires write access and Books to be quit.
Args: collection_id: The collection's numeric ID. book_id: The book's numeric ID.
Inputs: book_id (required), collection_id (required).
rename_collectionRename a collectionADestructiveIdempotent
Rename a user-created collection (built-in collections are refused). Requires write access and Books to be quit.
Args: collection_id: The collection's numeric ID. new_title: The new name.
Inputs: new_title (required), collection_id (required).
search_annotationsSearch annotationsARead-only
Search across every annotation field — selected (highlighted) text,
the surrounding paragraph, and the user's note body. Grouped by
book; a row's note, if any, is on a second line prefixed with
↳ note:. Use search_notes when you only want to find your
own written notes.
Args:
text: Substring to match anywhere in an annotation.
limit: Max annotations to return (1–500, default 50).
offset: Annotations to skip, for paging.
order_by: newest (default) or oldest first.
Inputs: text (required), limit, offset, order_by.
search_booksSearch books by title or authorARead-only
Search for books whose title or author contains query, ignoring
case, accents and quote/dash style ("don't" finds "Don’t", "godel"
finds "Gödel"). Output is one row per book, by book id:
[id] title by author. Use describe_book(id) for details.
Args: query: Text to find in the title or the author's name. limit: Max books to return (1–500, default 200). offset: Books to skip, for paging; a footer names the next offset when there are more.
Inputs: query (required), limit, offset.
search_books_by_titleSearch books by titleARead-only
Search for books by title (substring match, ignoring case, accents
and quote/dash style). Output is one row per match: [id] title by author. Use describe_book(id) for details, and
search_books to match authors too.
Args: title: The title to search for. limit: Max books to return (1–500, default 200). offset: Books to skip, for paging; a footer names the next offset when there are more.
Inputs: title (required), limit, offset.
search_collections_by_titleSearch collections by titleARead-only
Search for collections by title (substring match). Output is one
row per match: [id] title.
Args: title: The title to search for.
Inputs: title (required).
search_notesSearch notesARead-only
Search user notes (not highlights) by substring, grouped by book.
Output shows the highlighted passage on the primary row and the
matching note on a second line prefixed with ↳ note:.
Args:
note: Substring to find inside note bodies.
limit: Max annotations to return (1–500, default 50).
offset: Annotations to skip, for paging.
order_by: newest (default) or oldest first.
Inputs: note (required), limit, offset, order_by.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
Most tools target distinct resources or actions (collections, books, annotations, chapters), and descriptions clarify differences like search_books vs search_books_by_title or list_annotations vs list_all_annotations. However, several listing/searching tools for the same resource overlap somewhat, requiring careful reading to pick the right one.
Names are predominantly snake_case with a clear verb_noun structure (list_, get_, describe_, search_, create_, rename_, delete_, add_, remove_). Minor inconsistencies include 'recent_annotations' lacking a verb prefix and filtered book lists using 'get_' while full lists use 'list_', but the overall pattern is readable.
31 tools is heavy for the domain; many could be consolidated (e.g., the four reading-status book filters, the multiple book search tools, the several annotation listing tools). While the domain is complex, the rubric flags 25+ as too many, and several tools feel redundant.
Read coverage is extensive (books, collections, annotations, chapters, stats), but there are notable gaps in write operations: no tools to create/update/delete annotations or notes, no book metadata editing, no reading progress updates, and no ability to add/remove books from the library. Collection CRUD exists, suggesting write support is intended, so these gaps limit full lifecycle coverage.
Maintenance
Related MCP Connectors
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
Official Bookmax MCP server: search and save bookmarks, read notes and docs from AI assistants.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to read and write local Apple Books library, collections, and annotations. Supports searching, exporting, and modifying books and highlights via MCP tools.1MIT
- AlicenseBqualityBmaintenanceA local MCP server that gives Claude a durable reading room for EPUB and plain text books, enabling chunk-by-chunk navigation, annotations, progress tracking, and shared margin cards.26122MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for processing raw book notes into structured, searchable knowledge using embeddings and semantic search.-

Books Mandala MCPofficial
FlicenseNot gradedqualityCmaintenanceMCP server enabling AI assistants to search, browse, and discover books from Books Mandala's live catalog of 50,000+ titles.2-