apple-books-mcp
Apple Books MCP
Servidor del Protocolo de Contexto de Modelos (MCP) para Apple Books.
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 | 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 |
| 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-mcpUsando pip
pip install apple-books-mcpDespués de instalarlo, puedes ejecutar el servidor usando:
python -m apple_books_mcpUsando 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:latestSolicitud 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.

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 syncDepuració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-mcpAbrir 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 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-