Apple Books

Apple Books MCP

Servidor de Model Context Protocol (MCP) para Apple Books.

De un vistazo

• Retoma donde lo dejaste — Claude ve el capítulo en el que estás y su texto, además de los subrayados recientes del 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 — recupera tus subrayados, agrúpalos por tema y cítate a ti mismo.
• 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!

Herramientas disponibles

Colecciones

Herramienta	Descripción	Parámetros
list_all_collections	Listar todas las colecciones	limit?: int
get_collection_books	Obtener todos los libros de una colección	collection_id: str
describe_collection	Obtener detalles de una colección	collection_id: str
search_collections_by_title	Buscar colecciones por título	title: str

Edición de colecciones (opt-in)

Desactivada por defecto. Actívala añadiendo --enable-writes a los argumentos del servidor:

"args": ["apple-books-mcp@latest", "--enable-writes"]

Apple no proporciona una API de automatización para colecciones, por lo que estas escrituras van directamente a la base de datos de la biblioteca — con protecciones: cada escritura se rechaza mientras Books esté abierto, realiza primero una copia de seguridad automática compatible con WAL (~/.py_apple_books/backups/), valida el esquema y aborta si hay desviaciones, y solo toca colecciones creadas por el usuario (además de la membresía de "Quiero leer"). Eliminar una colección nunca elimina los libros que contiene.

⚠️ Si la sincronización de iCloud para colecciones está activada, las ediciones directas pueden no propagarse a otros dispositivos y pueden revertirse con una resincronización en la nube.

Herramienta	Descripción	Parámetros
create_collection	Crear una nueva colección	title: str, details?: str
rename_collection	Renombrar una colección creada por el usuario	collection_id: int, new_title: str
delete_collection	Eliminar una colección creada por el usuario (los libros no se tocan)	collection_id: int
add_book_to_collection	Añadir un libro a una colección (idempotente)	collection_id: int, book_id: int
remove_book_from_collection	Eliminar un libro de una colección (idempotente)	collection_id: int, book_id: int

Libros

Herramienta	Descripción	Parámetros
list_all_books	Listar todos los libros	limit?: int
describe_book	Obtener detalles de un libro concreto (metadatos, progreso, número de anotaciones, descripción)	book_id: str
list_annotations	Obtener 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	Buscar libros por título	title: str
get_books_by_genre	Obtener libros por género (coincidencia de subcadena)	genre: str, limit?: int

Estado de lectura

Herramienta	Descripción	Parámetros
get_books_in_progress	Obtener libros que se están leyendo actualmente	limit?: int
get_finished_books	Obtener libros que se han terminado	limit?: int
get_unstarted_books	Obtener libros aún no comenzados	limit?: int
get_recently_read_books	Obtener los libros abiertos más recientemente	limit?: int (predeterminado: 10)

Anotaciones

Herramienta	Descripción	Parámetros
list_all_annotations	Explorar todas las anotaciones agrupadas por libro, de más reciente a más antiguo	limit?: int
recent_annotations	Obtener las anotaciones más recientes (planas, con fecha + libro por fila)	limit?: int (predeterminado: 10)
describe_annotation	Obtener 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 «...»	annotation_id: int, chars_before?: int (predeterminado: 500), chars_after?: int (predeterminado: 500)
get_highlights_by_color	Subrayados de un color concreto, agrupados por libro	color: str, limit?: int
search_notes	Buscar notas del usuario (muestra subrayado + nota en línea)	note: str, limit?: int
search_annotations	Buscar en subrayados + notas + texto circundante	text: str, limit?: int
get_annotations_by_date_range	Anotaciones dentro de un rango de fechas (planas, 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	Obtener resumen de la biblioteca con estadísticas de lectura	None

Contenido de libros

Solo funciona con EPUB sin DRM (libros importados, Project Gutenberg, Standard Ebooks, etc.). Las compras de 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 contenidos 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 división opcional en 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ó la lectura (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
Currently Reading	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 EPUB 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 clic, accesibles desde el selector de prompts de Claude Desktop.

Prompt	Descripción	Argumentos
weekly_digest	Resumir lo que he leído y subrayado en la última semana	days?: int (predeterminado: 7)
library_snapshot	Una reflexión sobre toda mi vida de lectura	None
revisit_book	Revisitar tus notas y subrayados de un libro concreto	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 instalar, 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

Aviso de permiso en el primer uso (macOS)

En el primer uso, macOS preguntará si uvx (o python / docker, según cómo lo hayas lanzado) 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 sandbox 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 has clonado este repositorio, puedes probarlo con Claude Desktop usando 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

Apertura de 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, 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 capturas 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 a fondo.
4️⃣ Sube tus cambios y abre una Pull Request a main.

Proporciona un título y una descripción claros de tus cambios.

Licencia

Apple Books MCP está licenciado bajo la licencia Apache 2.0. Consulta el archivo LICENSE para más detalles.