Skip to main content
Glama
apple-books-mcp

apple-books-mcp

by vgnshiyer

Apple Books MCP

Servidor del Protocolo de Contexto de Modelos (MCP) para Apple Books.

Website PyPI License: Apache 2.0 Buy Me A Coffee

De un vistazo

  • Retoma donde lo dejaste — Claude puede ver el capítulo en el que estás y su texto, además de los subrayados recientes en el libro.

  • Amplía cualquier subrayado — obtén una explicación del párrafo circundante en contexto, con el ancla exacta que marcaste mostrada en «...».

  • Revisita un libro — extrae tus subrayados, agrúpalos por temas y deja que te los cite de vuelta.

  • Reflexiona sobre tu lectura — patrones entre libros, ideas recurrentes en tus subrayados, aquello que realmente te atrae.

https://github.com/user-attachments/assets/77a5a29b-bfd7-4275-a4af-8d6c51a4527e

¡Y mucho más!

Related MCP server: Co-Reading MCP

Herramientas disponibles

Colecciones

Herramienta

Descripción

Parámetros

list_all_collections

Lista todas las colecciones

limit?: int

get_collection_books

Obtiene todos los libros de una colección

collection_id: str

describe_collection

Obtiene detalles de una colección

collection_id: str

search_collections_by_title

Busca colecciones por título

title: str

Libros

Herramienta

Descripción

Parámetros

list_all_books

Lista todos los libros

limit?: int

describe_book

Obtiene detalles de un libro en particular (metadatos, progreso, número de anotaciones, descripción)

book_id: str

list_annotations

Obtiene todas las anotaciones de un libro (id + texto + capítulo por fila, ordenadas por capítulo)

book_id: int, limit?: int

search_books_by_title

Busca libros por título

title: str

get_books_by_genre

Obtiene libros por género (coincidencia de subcadena)

genre: str, limit?: int

Estado de lectura

Herramienta

Descripción

Parámetros

get_books_in_progress

Obtiene los libros que se están leyendo actualmente

limit?: int

get_finished_books

Obtiene los libros que ya se han terminado

limit?: int

get_unstarted_books

Obtiene los libros que aún no se han empezado

limit?: int

get_recently_read_books

Obtiene los libros abiertos más recientemente

limit?: int (predeterminado: 10)

Anotaciones

Herramienta

Descripción

Parámetros

list_all_annotations

Explora todas las anotaciones agrupadas por libro, las más recientes primero

limit?: int

recent_annotations

Obtiene las anotaciones más recientes (plano, con fecha + libro por fila)

limit?: int (predeterminado: 10)

describe_annotation

Obtiene los detalles completos de una sola anotación

annotation_id: str

get_annotation_context

Ventana de texto alrededor de un subrayado (el párrafo en el que se encuentra), con el subrayado marcado como «...»

annotation_id: int, chars_before?: int (predeterminado: 500), chars_after?: int (predeterminado: 500)

get_highlights_by_color

Subrayados de un color en particular, agrupados por libro

color: str, limit?: int

search_notes

Busca notas de usuario (muestra el subrayado + la nota en línea)

note: str, limit?: int

search_annotations

Busca entre subrayados + notas + texto circundante

text: str, limit?: int

get_annotations_by_date_range

Anotaciones dentro de un rango de fechas (plano, con fecha + libro por fila)

after?: YYYY-MM-DD, before?: YYYY-MM-DD, limit?: int

Estadísticas de la biblioteca

Herramienta

Descripción

Parámetros

get_library_stats

Obtiene un resumen de la biblioteca con estadísticas de lectura

None

Contenido del libro

Solo funciona para EPUBs sin DRM (libros importados, Project Gutenberg, Standard Ebooks, etc.). Las compras de la Apple Books Store están protegidas por FairPlay y devuelven un error claro. Los libros solo en iCloud devuelven una pista de "no descargado".

Herramienta

Descripción

Parámetros

list_book_chapters

Tabla de contenido de un libro (títulos de capítulos, orden, anidamiento)

book_id: int

get_chapter_content

Contenido en texto plano de un capítulo, con corte opcional de offset + max_chars

book_id: int, chapter_id: str, offset?: int, max_chars?: int

get_current_reading_position

El capítulo donde el usuario dejó de leer por última vez (mediante el marcador automático CFI de Apple Books)

book_id: int

Recursos disponibles

Objetos de datos adjuntables accesibles desde el selector de recursos de Claude Desktop.

Recurso

URI

Descripción

Lectura actual

apple-books://currently-reading

El libro que estás leyendo ahora mismo: el libro en progreso abierto más recientemente, con metadatos, el capítulo donde lo dejaste más una vista previa de su texto (para EPUBs sin DRM) y anotaciones recientes. Adjúntalo a cualquier conversación para centrar a Claude en tu lectura actual.

Prompts disponibles

Flujos de trabajo de un solo clic, accesibles desde el selector de prompts de Claude Desktop.

Prompt

Descripción

Argumentos

weekly_digest

Resume lo que he leído y subrayado en la última semana

days?: int (predeterminado: 7)

library_snapshot

Una reflexión sobre toda mi vida lectora

None

revisit_book

Revisa tus notas y subrayados de un libro específico

book_title: str

Instalación

Usando uv (recomendado)

uvx se puede usar para ejecutar directamente apple-books-mcp (sin instalarlo).

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

Usando pip

pip install apple-books-mcp

Después de instalarlo, puedes ejecutar el servidor usando:

python -m apple_books_mcp

Usando Docker

docker run -v ~/Library/Containers/com.apple.iBooksX/Data/Documents:/root/Library/Containers/com.apple.iBooksX/Data/Documents:ro ghcr.io/vgnshiyer/apple-books-mcp:latest

Solicitud de permiso en la primera ejecución (macOS)

En el primer uso, macOS preguntará si uvx (o python / docker, dependiendo de cómo lo hayas iniciado) puede "acceder a datos de otras aplicaciones". Haz clic en Permitir: el MCP lee el contenedor privado de Apple Books en ~/Library/Containers/com.apple.iBooksX/, que macOS trata como datos en espacio aislado de otra aplicación. El acceso es de solo lectura y está limitado a ese contenedor; el servidor se inicia correctamente de cualquier manera, pero sin permiso, todas las herramientas devuelven resultados vacíos.

Solicitud de permiso de macOS: uvx desea acceder a datos de otras aplicaciones. No permitir / Permitir.

Configuración

Configuración de Claude Desktop

Usando uvx (recomendado)

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "uvx",
            "args": [ "apple-books-mcp@latest" ]
        }
    }
}

Usando python

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "python",
            "args": ["-m", "apple_books_mcp"]
        }
    }
}

Usando Docker

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "docker",
            "args": [
                "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"
            ]
        }
    }
}

Próximas funciones

  • [ ] Acceso al contenido de PDF (actualmente solo EPUB)

  • [ ] Contexto de anotación más completo mediante resolución de CFI → párrafo

Contribución

¡Gracias por considerar contribuir a este proyecto!

Desarrollo

Si clonaste este repositorio, puedes probarlo usando Claude Desktop con la siguiente configuración:

Usa uv venv para crear un entorno virtual e instalar las dependencias.

uv venv
uv sync

Depuración

Con Claude Desktop

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/apple-books-mcp/",
                "run",
                "apple_books_mcp",
                "-v"
            ]
        }
    }
}

Con inspector

npx @modelcontextprotocol/inspector uvx apple-books-mcp

Abrir incidencias

Si encuentras un error, tienes una solicitud de función o quieres discutir algo relacionado con el proyecto, abre una incidencia en el repositorio de GitHub. Al abrir una incidencia, por favor proporciona:

Informes de errores: Describe el problema en detalle. Incluye pasos para reproducir el error si es posible, junto con cualquier mensaje de error o captura de pantalla.

Solicitudes de funciones: Explica claramente la nueva función que te gustaría ver añadida al proyecto. Proporciona contexto sobre por qué esta función sería beneficiosa.

Discusiones generales: Siéntete libre de iniciar discusiones sobre temas más amplios relacionados con el proyecto.

Contribuir

1️⃣ Haz un fork del repositorio de GitHub https://github.com/vgnshiyer/apple-books-mcp
2️⃣ Crea una nueva rama para tus cambios (git checkout -b feature/my-new-feature).
3️⃣ Realiza tus cambios y pruébalos exhaustivamente.
4️⃣ Envía tus cambios y abre un Pull Request a main.

Por favor, proporciona un título y una descripción claros de tus cambios.

Licencia

Apple Books MCP tiene la licencia Apache 2.0. Consulta el archivo LICENSE para obtener más detalles.

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