Skip to main content
Glama
apple-books-mcp

apple-books-mcp

by vgnshiyer

Apple Books MCP

Model Context Protocol (MCP) server for Apple Books.

Website PyPI License: Apache 2.0 Buy Me A Coffee

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 as book_id, annotation_id or collection_id. A numeric string such as "175" is accepted too; true, false and 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 before day, local time (flat, with date + book per row)

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 offset + max_chars slicing. chapter_id="current" (the default) reads the chapter you're on in Apple Books

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

apple-books://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 get_chapter_content and list_annotations. Attach to any conversation to focus Claude on your current read.

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) and py-apple-books >= 1.10 (< 2).

uvx runs apple-books-mcp without a separate install step.

brew install uv  # for macos
uvx apple-books-mcp --version

The 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 --version

Upgrade 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:latest

In 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 permission prompt: uvx would like to access data from other apps. Don't Allow / Allow.

macOS asks about the program Claude launches, not about apple-books-mcp itself:

  • uvx with the recommended Claude Desktop config (the prompt above);

  • the Python interpreter with the pip config;

  • claude when 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 SystemPolicyAppData

This 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.

{
    "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-mcp once. The same uvx config then uses the installed copy and starts in about a second without contacting PyPI. Installed copies don't update themselves: run uv tool upgrade apple-books-mcp to 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-mcp

and 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

APPLE_BOOKS_MCP_ENABLE_WRITES

off

1, true or yes turns on collection editing, like --enable-writes.

APPLE_BOOKS_MCP_THREADS

8

How many tool calls run at once. 0 runs them one at a time on the server's event loop, as before 0.9. Lower values also cap memory on very large libraries.

APPLE_BOOKS_DATA_DIR

Apple Books' own folder

The Apple Books Documents folder to read (the one holding BKLibrary/ and AEAnnotation/).

APPLE_BOOKS_QUERY_TIMEOUT

30

Seconds a library query may run before it is stopped; 0 means no limit.

Troubleshooting

Where to look

  • uvx apple-books-mcp --doctor in 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 your mcpServers key) 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.log lists failures. Its "Server started and connected successfully" line only means the process was launched, not that it works.

  • ~/Library/Logs/Claude/main.log records "Connected to apple-books-mcp (N tools)" when a Claude Code or Cowork session in Desktop loaded the tools.

  • uvx apple-books-mcp --version in 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. Run uv cache clean apple-books-mcp, check that uvx apple-books-mcp --version reports 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 --version once 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.log is 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 /mcp and 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 pytest

To build the Claude Desktop extension locally, install the pinned packer, then build:

npm ci --ignore-scripts --prefix mcpb
uv run python scripts/build_mcpb.py

This 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-mcp

Opening 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 tools
add_book_to_collectionAdd a book to a collectionC
Idempotent

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 collectionA
DestructiveIdempotent

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 annotationA
Read-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 bookA
Read-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 collectionB
Read-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 highlightA
Read-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 rangeA
Read-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 Title

Args: 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 genreA
Read-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 progressA
Read-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 textA
Read-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 booksA
Read-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 positionA
Read-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 booksA
Read-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 colorA
Read-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 statsA
Read-only

Get a summary of your Apple Books library with reading stats.

Inputs: no named parameters.

get_recently_read_booksRecently read booksA
Read-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 booksA
Read-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 annotationsA
Read-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 booksA
Read-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 collectionsA
Read-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 annotationsA
Read-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 chaptersA
Read-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 annotationsA
Read-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 Title

Args: 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 collectionA
DestructiveIdempotent

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 collectionA
DestructiveIdempotent

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 annotationsA
Read-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 authorA
Read-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 titleA
Read-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 titleA
Read-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 notesA
Read-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

    A3.5/5.0

    Scored across 31 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers