{
  "markdown": "# Apple Books MCP\n\n<!-- mcp-name: io.github.vgnshiyer/apple-books-mcp -->\n\nModel Context Protocol (MCP) server for Apple Books.\n\n[![Website](https://img.shields.io/badge/website-vgnshiyer.me-CC785C)](https://vgnshiyer.me/AppleBooksMcp)\n![](https://badge.mcpx.dev?type=server 'MCP Server')\n[![PyPI](https://img.shields.io/pypi/v/apple-books-mcp.svg)](https://pypi.org/project/apple-books-mcp/)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![](https://img.shields.io/badge/Follow-vgnshiyer-0A66C2?logo=linkedin)](https://www.linkedin.com/comm/mynetwork/discovery-see-all?usecase=PEOPLE_FOLLOWS&followMember=vgnshiyer)\n[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Donate-yellow.svg?logo=buymeacoffee)](https://www.buymeacoffee.com/vgnshiyer)\n\n## At a glance\n\n* **Pick up where you left off** — Claude sees the chapter you're on *and* its text, plus recent highlights in the book.\n* **Expand on any highlight** — get the surrounding paragraph explained in context, with the exact anchor you marked shown in `«...»`.\n* **Revisit a book** — pull your highlights, cluster them by theme, and quote you back to yourself.\n* **Reflect on your reading** — patterns across books, recurring ideas in your highlights, what you're actually drawn to.\n\nhttps://github.com/user-attachments/assets/77a5a29b-bfd7-4275-a4af-8d6c51a4527e\n\nAnd much more!\n\n## Available Tools\n\n### Collections\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| list_all_collections | List all collections | limit?: int |\n| get_collection_books | Get all books in a collection | collection_id: str |\n| describe_collection | Get details of a collection | collection_id: str |\n| search_collections_by_title | Search for collections by title | title: str |\n\n### Editing collections (opt-in)\n\nOff by default. Enable by adding `--enable-writes` to the server args:\n\n```json\n\"args\": [\"apple-books-mcp@latest\", \"--enable-writes\"]\n```\n\nApple 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.\n\n> ⚠️ If iCloud sync for collections is enabled, direct edits may not propagate to other devices and can be reverted by a cloud re-sync.\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| create_collection | Create a new collection | title: str, details?: str |\n| rename_collection | Rename a user-created collection | collection_id: int, new_title: str |\n| delete_collection | Delete a user-created collection (books untouched) | collection_id: int |\n| add_book_to_collection | Add a book to a collection (idempotent) | collection_id: int, book_id: int |\n| remove_book_from_collection | Remove a book from a collection (idempotent) | collection_id: int, book_id: int |\n\n### Books\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| list_all_books | List all books | limit?: int |\n| describe_book | Get details of a particular book (metadata, progress, annotation count, description) | book_id: str |\n| list_annotations | Get all annotations for a book (id + text + chapter per row, chapter-ordered) | book_id: int, limit?: int |\n| search_books_by_title | Search for books by title | title: str |\n| get_books_by_genre | Get books by genre (substring match) | genre: str, limit?: int |\n\n### Reading Status\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| get_books_in_progress | Get books currently being read | limit?: int |\n| get_finished_books | Get books that have been finished | limit?: int |\n| get_unstarted_books | Get books not yet started | limit?: int |\n| get_recently_read_books | Get most recently opened books | limit?: int (default: 10) |\n\n### Annotations\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| list_all_annotations | Browse every annotation grouped by book, newest first | limit?: int |\n| recent_annotations | Get most recent annotations (flat, with date + book per row) | limit?: int (default: 10) |\n| describe_annotation | Get full details of a single annotation | annotation_id: str |\n| 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) |\n| get_highlights_by_color | Highlights of a particular color, grouped by book | color: str, limit?: int |\n| search_notes | Search user notes (shows highlight + note inline) | note: str, limit?: int |\n| search_annotations | Search across highlights + notes + surrounding text | text: str, limit?: int |\n| get_annotations_by_date_range | Annotations within a date range (flat, with date + book per row) | after?: YYYY-MM-DD, before?: YYYY-MM-DD, limit?: int |\n\n### Library Stats\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| get_library_stats | Get library summary with reading stats | None |\n\n### Book Content\n\nOnly works for non-DRM EPUBs (imported books, Project Gutenberg, Standard Ebooks, etc.). Apple Books Store purchases are FairPlay-protected and return a clear error. iCloud-only books return a \"not downloaded\" hint.\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| list_book_chapters | Table of contents for a book (chapter titles, order, nesting) | book_id: int |\n| get_chapter_content | Plain-text content of a chapter, with optional `offset` + `max_chars` slicing | book_id: int, chapter_id: str, offset?: int, max_chars?: int |\n| get_current_reading_position | The chapter the user last left off reading (via Apple Books' auto-bookmark CFI) | book_id: int |\n\n## Available Resources\n\nAttachable data objects accessible from Claude Desktop's resource picker.\n\n| Resource | URI | Description |\n|----------|-----|-------------|\n| Currently Reading | `apple-books://currently-reading` | The book you're reading right now — most recently opened in-progress book, with metadata, **the chapter you left off on plus a preview of its text** (for non-DRM EPUBs), and recent annotations. Attach to any conversation to focus Claude on your current read. |\n\n## Available Prompts\n\nOne-click workflows, accessible from Claude Desktop's prompt picker.\n\n| Prompt | Description | Arguments |\n|--------|-------------|-----------|\n| weekly_digest | Summarize what I've read and highlighted in the past week | days?: int (default: 7) |\n| library_snapshot | A reflection on my whole reading life | None |\n| revisit_book | Revisit your notes and highlights from a specific book | book_title: str |\n\n## Installation\n\n### Using uv (recommended)\n\n[uvx](https://docs.astral.sh/uv/guides/tools/) can be used to directly run apple-books-mcp (without installing it).\n\n```bash\nbrew install uv  # for macos\nuvx apple-books-mcp\n```\n\n### Using pip\n\n```bash\npip install apple-books-mcp\n```\n\nAfter installing, you can run the server using:\n\n```bash\npython -m apple_books_mcp\n```\n\n### Using Docker\n\n```bash\ndocker 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\n```\n\n## First-run permission prompt (macOS)\n\nOn first use, macOS will ask whether `uvx` (or `python` / `docker`, depending on how you launched) may \"access data from other apps.\" Click **Allow** — the MCP reads Apple Books' private container at `~/Library/Containers/com.apple.iBooksX/`, which macOS treats as another app's sandboxed data. Access is read-only and scoped to that container; the server starts successfully either way, but without permission every tool comes back empty.\n\n![macOS permission prompt: uvx would like to access data from other apps. Don't Allow / Allow.](./docs/permission-prompt.png)\n\n## Configuration\n\n### Claude Desktop Setup\n\n#### Using uvx (recommended)\n\n```json\n{\n    \"mcpServers\": {\n        \"apple-books-mcp\": {\n            \"command\": \"uvx\",\n            \"args\": [ \"apple-books-mcp@latest\" ]\n        }\n    }\n}\n```\n\n#### Using python\n\n```json\n{\n    \"mcpServers\": {\n        \"apple-books-mcp\": {\n            \"command\": \"python\",\n            \"args\": [\"-m\", \"apple_books_mcp\"]\n        }\n    }\n}\n```\n\n#### Using Docker\n\n```json\n{\n    \"mcpServers\": {\n        \"apple-books-mcp\": {\n            \"command\": \"docker\",\n            \"args\": [\n                \"run\", \"-i\", \"--rm\",\n                \"-v\", \"~/Library/Containers/com.apple.iBooksX/Data/Documents:/root/Library/Containers/com.apple.iBooksX/Data/Documents:ro\",\n                \"ghcr.io/vgnshiyer/apple-books-mcp:latest\"\n            ]\n        }\n    }\n}\n```\n\n## Upcoming Features\n\n- [ ] PDF content access (currently EPUB-only)\n- [ ] fuller annotation context via CFI → paragraph resolution\n\n## Contribution\n\nThank you for considering contributing to this project!\n\n### Development\n\nIf you cloned this repository, you can test it using Claude Desktop with below configuration:\n\nUse `uv venv` to create a virtual environment and install the dependencies.\n\n```bash\nuv venv\nuv sync\n```\n\n#### Debugging\n\n**With Claude Desktop**\n\n```json\n{\n    \"mcpServers\": {\n        \"apple-books-mcp\": {\n            \"command\": \"uv\",\n            \"args\": [\n                \"--directory\",\n                \"/path/to/apple-books-mcp/\",\n                \"run\",\n                \"apple_books_mcp\",\n                \"-v\"\n            ]\n        }\n    }\n}\n```\n\n**With inspector**\n\n```bash\nnpx @modelcontextprotocol/inspector uvx apple-books-mcp\n```\n\n### Opening Issues\nIf 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:\n\n**Bug Reports**: Describe the issue in detail. Include steps to reproduce the bug if possible, along with any error messages or screenshots.\n\n**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.\n\n**General Discussions**: Feel free to start discussions on broader topics related to the project.\n\n### Contributing\n\n1️⃣ Fork the GitHub repository https://github.com/vgnshiyer/apple-books-mcp \\\n2️⃣ Create a new branch for your changes (git checkout -b feature/my-new-feature). \\\n3️⃣ Make your changes and test them thoroughly. \\\n4️⃣ Push your changes and open a Pull Request to `main`.\n\n*Please provide a clear title and description of your changes.*\n\n## License\n\nApple Books MCP is licensed under the Apache 2.0 license. See the LICENSE file for details.\n",
  "bytes": 10807,
  "sha": "93dbedb344b76124dc58929f81fbac5984a19def909c14a4c3d05cad6acb2d41",
  "repo_slug": "vgnshiyer/apple-books-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vgnshiyer_apple_books_mcp_d688a84e/readme"
}