kavita-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| KAVITA_URL | No | Kavita, as kavita-mcp reaches it | http://kavita:5000 |
| KAVITA_API_KEY | Yes | A Kavita auth key (user settings → Auth keys). The tools act as its user. | |
| FILEBROWSER_URL | No | File Browser URL, with its login method noauth | http://kavita-upload:8080 |
| KAVITA_MCP_HOST | No | Host for the MCP server endpoint | 0.0.0.0 |
| KAVITA_MCP_PORT | No | Port for the MCP server endpoint; the endpoint is /mcp | 8000 |
| MAX_IMAGE_BYTES | No | Cap on each embedded image | 1048576 |
| KAVITA_PUBLIC_URL | No | Kavita's public URL, for links in answers | |
| MAX_MARKDOWN_BYTES | No | Cap on markdown (including data URIs) | 2097152 |
| KAVITA_REPORTS_PATH | No | The Reports library's folder as Kavita sees it | /reports |
| KAVITA_MCP_TRANSPORT | No | Transport type, or stdio | streamable-http |
| SCAN_TIMEOUT_SECONDS | No | How long scan_now waits for Kavita | 60 |
| FILEBROWSER_REPORTS_DIR | No | The same folder as File Browser sees it | /Reports |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Publishes markdown reports as EPUB books into the user's Kavita library (library "Reports"), where they reach their e-reader through OPDS, and reads the user's own reading state across all their libraries: what they are in the middle of, what is unread, their want-to-read queue. A new report appears in Kavita about 6 minutes after add_document, or within seconds with scan_now. Call list_collections before inventing a collection name. There are no tags. Book contents are never returned.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| add_documentA | Build an EPUB from markdown and put it in the Kavita library "Reports". Publishing a title that already exists replaces that book (same folder, same Kavita series, reading progress kept); a new title is a new book. Images only as data: URIs (base64, up to 1 MiB each); any other image (a URL or a path) becomes its alt text. No tags. Returns the series ID when Kavita already has the book or scan_now found it; otherwise Kavita lists it in about 6 minutes. To move a book to another collection, use update_document. |
| update_documentA | Change the summary or the collection of a report published with add_document. Works only on reports (the "Reports" library), and needs the Kavita series ID: for a report Kavita hasn't listed yet, call add_document again with the same title instead. collection moves the book: it leaves the collection it was published with and joins the new one; collections added by hand stay. |
| delete_documentA | Delete a report published with add_document: its file and, after Kavita's next scan, its Kavita entry. Only reports can be deleted, never books from other libraries. |
| list_libraryA | List the user's books across all their Kavita libraries, one compact row each (series ID, title, author, library, added, word count, pages, read status, progress). Returns total and next_page. |
| searchB | Find books whose title matches, with the same rows as list_library. |
| get_documentB | Details of one book: author, summary, collections, word count, pages, reading progress, added date, file path, want-to-read, Kavita link. Never the content. |
| list_collectionsA | The user's collection names and library names, to reuse instead of inventing near-duplicates before add_document. |
| want_to_readC | The user's "read next" queue, shown in Kavita and over OPDS on the e-reader. |
| reading_statusC | Answers "what am I in the middle of?", "what haven't I read?" and "what's next?". |
| mark_readA | Mark every page of the book as read (replaces the current position). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 10 tools
Most tools are clearly distinct, but reading_status and want_to_read overlap significantly — reading_status explicitly claims to answer "what's next?" while want_to_read is the read-next queue, so an agent could easily pick the wrong one. list_library and search also return identical row shapes and differ only by filtering, which is defensible but adds another soft boundary.
Seven tools follow a clean verb_noun pattern (get_document, add_document, update_document, delete_document, list_library, list_collections, mark_read), but search is a bare verb with no noun and want_to_read / reading_status are noun-ish phrases with no action verb. The mix is still readable but not a single predictable convention.
Ten tools is well within the sensible range and each maps to a plausible reading-library operation. The only redundancy is the want_to_read / reading_status pair, which could arguably collapse into one query tool.
Core lifecycle for reports is covered (add/get/update/delete plus list and search), but there are real gaps: no mark_unread or partial progress update, no way to add/remove items from the want-to-read queue (read-only), and update_document cannot change titles or content and only works on reports. Agents will hit dead ends on queue management and un-reading.