# Calibre-Web MCP > Calibre-Web connects your AI client to your private digital library instance, letting you query and manage thousands of ebooks using natural language. You can automatically discover catalog structures, list books from specific shelves, and prepare structured metadata for e-reader synchronization (Kobo). ## Overview - **Category:** knowledge-management - **Price:** Free - **Tags:** ebooks, calibre, opds, kobo-sync, digital-library ## Description Talking to a large book collection used to mean manually navigating complex websites or generating XML feeds just to see what's in it. Now, you treat your entire digital library like a searchable database. This MCP lets your agent interact with the full structure of your Calibre-Web instance using plain language commands. You can ask for an overview of all categories or check exactly which books are on a specific curated shelf without ever touching a URL. Plus, if you use Kobo e-readers, the tool handles the metadata formatting and secure links needed to sync your collection directly. Connect this MCP via Vinkius and let your agent do the heavy lifting, giving you instant access to every piece of book data. ## Tools ### sync_kobo_library Generates structured metadata and secure download links necessary for synchronizing your library contents with Kobo devices. ### get_opds_catalog Retrieves the primary, comprehensive XML feed that maps out your entire library's structure and categories. ### get_opds_shelf Fetches the specific OPDS feed containing only the books belonging to a designated shelf ID number. ## Prompt Examples **Prompt:** ``` Retrieve the main OPDS catalog from my library. ``` **Response:** ``` I've accessed your Calibre-Web OPDS feed. I can see categories for 'Newest', 'Authors', 'Series', and 'Hot'. Which section would you like to explore? ``` **Prompt:** ``` Show me the books available on shelf ID 5. ``` **Response:** ``` Fetching shelf 5... I found 3 books: 'The Great Gatsby', '1984', and 'Brave New World'. Would you like the metadata for any of these? ``` **Prompt:** ``` Sync my Kobo library and provide the download links. ``` **Response:** ``` Syncing with Kobo... I've generated the metadata for your library. You have 12 books ready for sync, including direct download links for your device. ``` ## Capabilities ### Discovering full catalog structure Retrieves the main OPDS feed, allowing your AI client to browse all categories, authors, and recent additions in your library. ### Listing contents of specific shelves Queries a defined shelf ID and returns a list of every book contained within that user-defined collection. ### Generating sync files for e-readers Fetches structured metadata and download links, specifically formatted for easy synchronization with Kobo devices. ## Use Cases ### Auditing an academic collection The librarian needs to confirm that all 50 books on the 'Victorian Poetry' shelf are present and correctly cataloged. Instead of running a complex manual query, they ask their agent to execute `get_opds_shelf` with the specific ID. The response provides an immediate list, letting them verify metadata integrity in seconds. ### Preparing for a book fair display An author needs to quickly show potential buyers that their best-selling series is properly cataloged and grouped. They use the agent to call `get_opds_catalog`, which pulls the main feed, allowing them to confirm the existence of the 'Series' category before building the physical display. ### Mass transferring books to a client A digital archivist needs to send a batch of research documents to a client using Kobo. They use `sync_kobo_library`, providing only their sync token, and the tool returns all the necessary structured data and direct download links needed for seamless transfer. ### Verifying library structure after migration A system admin migrated a large collection but can't remember the IDs. They use the agent to call `get_opds_catalog` first, which shows them all available categories. Then they follow up by asking the tool to check specific shelf IDs using `get_opds_shelf`, confirming the data moved correctly. ## Benefits - Stop manually copying XML feeds. You can ask your agent to run `get_opds_catalog` and instantly get a structured view of every category and author in your entire collection. - Need to check if the right books are on a specific shelf? Use `get_opds_shelf`. Just feed it the ID, and you get an instant list of contents without clicking through multiple web pages. - The tool handles e-reader preparation. Running `sync_kobo_library` automatically gathers all necessary metadata and direct download links for Kobo devices—no more manual exports. - It centralizes access. Your agent interacts with your library data as if it were a simple API, letting you bypass the need to learn Calibre-Web's specific web interface quirks. - Saves time on verification tasks. If you suspect metadata is wrong or a shelf is incomplete, running `get_opds_shelf` gives immediate proof of what's available. ## How It Works The bottom line is that you talk naturally, and this MCP translates those requests into specific API calls to pull book data from your self-hosted instance. 1. First, subscribe to this MCP and provide your Calibre-Web instance URL along with any required credentials. 2. Next, tell your AI client what you need—for example, 'Show me the books on shelf ID 5' or 'Get the full catalog feed.' 3. The tool executes the request against your private library data and hands back structured metadata or a list of titles for your agent to process. ## Frequently Asked Questions **How do I check my entire book catalog using get_opds_catalog?** You ask your agent to run `get_opds_catalog`. It pulls the main OPDS feed, which gives you a structured view of all categories and authors available in your library immediately. **What is the difference between get_opds_catalog and get_opds_shelf?** The catalog tool gets the full map of everything. The shelf tool, `get_opds_shelf`, limits the output to only what belongs on a specific, curated shelf ID you name. **Do I need a Kobo token for sync_kobo_library?** Yes, `sync_kobo_library` requires your dedicated Kobo Token. This ensures the generated metadata and download links are secure and usable by your e-reader device. **Can I use this MCP to search for a book title?** The tool focuses on catalog structure, not free-text searching. You must first retrieve the list of titles using `get_opds_catalog` or `get_opds_shelf`, and then your agent can help you search that structured data. **What specific metadata fields does the `get_opds_catalog` tool return?** It returns structured data covering key library elements, including titles, authors, publication dates, and associated shelf IDs. This allows your agent to understand both the book's details and where it lives within your collection. **What happens if I use `get_opds_shelf` with an invalid ID?** The MCP will return a specific error message. This tells you that the requested shelf ID either doesn't exist or is inaccessible to your connected account, letting you pinpoint the problem quickly. **Are there any rate limits I should know about when running `sync_kobo_library`?** While designed for typical use, repeated, large-scale syncs in quick succession might hit throttling limits imposed by Calibre-Web. If you encounter errors, try spacing out your synchronization requests. **Do I need to configure any specific credentials beyond the base URL?** Yes. While the primary setup requires the instance URL, if your self-hosted Calibre-Web requires advanced authentication, you'll need to input additional username or API keys for full access. **Can I browse my entire library structure through the AI?** Yes. By using the `get_opds_catalog` tool, the agent retrieves the root XML feed of your Calibre-Web instance, allowing it to see categories, authors, and series as defined in your OPDS settings. **How do I list books from a specific custom shelf?** You can use the `get_opds_shelf` tool by providing the specific `shelf_id`. The AI will then return the list of books and metadata associated with that particular shelf. **Does this support syncing my Kobo e-reader?** Yes. If you provide your `CALIBRE_WEB_KOBO_TOKEN`, you can use the `sync_kobo_library` tool to get structured metadata and download links specifically formatted for Kobo device synchronization.