Kavita MCP Connector
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Kavita MCP Connector Find the series 'One Piece' in my Kavita library and show its metadata"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
kavita-mcp (Kavita MCP connector)
MCP connector for a self-hosted Kavita server (v0.9.1.x). It speaks the HTTP API over stdio and over stateless Streamable HTTP on localhost.
Kavita is GPL-3.0 software. This connector does not copy that code. It only calls the HTTP API on the server you configure. It is not affiliated with Kavita or Kavitareader. Bring your own Auth Key from User Settings on your server.
The spec file kavita.openapi.json has 517 operations across 46 tags. This connector covers 453 of them in 43 tools. It leaves out 64 endpoints that return files, feeds, or client-sync protocols. scripts/gen-operations.mjs writes src/operations.ts from the spec. Do not edit that file by hand.
Self-hosted servers only. There is no default base URL. KAVITA_URL is required. Hosts on kavitareader.com and its subdomains are refused. That domain is the Kavita+ license and cloud service.
Setup
npm install
npm run ci
npm start
npm run start:httpnpm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.
{
"mcpServers": {
"kavita": {
"command": "node",
"args": ["/workspace/connectors/kavita/dist/index.js"],
"env": {
"KAVITA_URL": "http://127.0.0.1:5000",
"KAVITA_API_KEY": "...",
"KAVITA_ALLOW_WRITES": "false",
"KAVITA_TOOLSETS": "server,library,series,collection,readinglist,search"
}
}
}
}Regenerate the registry after an OpenAPI bump.
npm run gen:operationsscripts/live-check.mjs talks to a real server over stdio. It needs KAVITA_URL and KAVITA_API_KEY, sets KAVITA_TOOLSETS=all and KAVITA_ALLOW_WRITES=true, and prints pass or fail lines only. The parent runs it. This workspace does not start Kavita.
Related MCP server: komga-mcp
Config
Variable | Meaning |
| Required. Self-hosted origin, |
| Auth Key from User Settings. Sent as the |
| Optional login. Set together with |
| Password for that login. The connector posts |
| Must be the literal |
| Comma list of toolsets, or |
| Local request budget. Default 30. Cache hits do not spend it. |
| Upstream timeout. Default 20000. |
| Read cache TTL. Default 60. Writes clear the cache. |
| Contact token in the User-Agent. Must not contain the key or password. |
|
|
| HTTP port. Default 3000. |
Safety
GET is a read. POST, PUT, and DELETE are writes, except a reviewed list of POST queries in READ_POST_PATHS (series filters, search-style lookups, stats-like reads). A few GETs that start logins or update checks are writes (GET_SIDE_EFFECT_PATHS). Anything not on the read list stays a write.
A write needs confirm: true as a boolean and KAVITA_ALLOW_WRITES=true. The string "true" is rejected. Otherwise the tool returns a dry-run preview of method, path, query, and redacted body, and it sends nothing. Destructive, credential, and exposure operations add a warning line on the tool and on the preview. That set covers deletes, scans, cache clears, user invites and role changes, Auth Key create and revoke, password reset, settings, license, scrobbling tokens, OAuth and OIDC, and email.
Auth Key create and rotate return the key once, with a shown-only-once note. Later list and get calls redact it. Account apiKey and email are redacted. Library folder paths stay in successful responses. Error text drops stack traces and filesystem paths.
HTTP 401 is unauthorized. HTTP 403 is forbidden. HTTP 404 is not found. HTTP 400 and 422 are invalid input. HTTP 429 includes Retry-After. Other failures are server, network, or timeout. Response bodies are capped.
Tools
Default KAVITA_TOOLSETS publishes 12 tools (186 operations). KAVITA_TOOLSETS=all publishes 43 tools (453 operations, 236 reads and 217 writes). Each tool takes action plus optional params, query, body, and confirm.
action help with optional target returns the path, query, and body fields for one action. Descriptions list action names only, so the tool list stays small.
Toolset | Tool | Operations | Default |
server |
| 17 | yes |
library |
| 23 | yes |
series |
| 33 | yes |
collection |
| 12 | yes |
readinglist |
| 27 | yes |
search |
| 4 | yes |
metadata |
| 14 | yes |
person |
| 10 | yes |
chapter |
| 5 | yes |
volume |
| 4 | yes |
stats |
| 33 | yes |
wanttoread |
| 4 | yes |
account |
| 28 | no |
activity |
| 1 | no |
admin |
| 1 | no |
annotation |
| 12 | no |
book |
| 2 | no |
cbl |
| 13 | no |
color_scape |
| 3 | no |
device |
| 10 | no |
| 1 | no | |
filter |
| 12 | no |
font |
| 3 | no |
health |
| 1 | no |
image |
| 3 | no |
kavita_plus_audit |
| 6 | no |
license |
| 13 | no |
locale |
| 1 | no |
manage |
| 2 | no |
oauth |
| 2 | no |
oidc |
| 2 | no |
panels |
| 2 | no |
plugin |
| 5 | no |
rating |
| 4 | no |
reader |
| 35 | no |
reading_profile |
| 16 | no |
review |
| 5 | no |
scrobbling |
| 19 | no |
settings |
| 20 | no |
stream |
| 17 | no |
theme |
| 6 | no |
upload |
| 12 | no |
users |
| 10 | no |
Example. List libraries, then preview a scan.
{ "action": "get_libraries" }{ "action": "post_scan", "query": { "libraryId": "1", "force": "false" } }Add "confirm": true only after KAVITA_ALLOW_WRITES=true.
Exclusions
64 operations are in EXCLUSIONS, each with a reason. The coverage test checks that the spec equals the registry plus that list, in both directions.
Download. Zip archives and the size helpers for those archives.
Opds. XML catalogues, and the Auth Key sits in the path.
Koreader and Tachiyomi. Client sync protocols, not management APIs.
Image cover and page bytes, Reader image, pdf, and thumbnail bytes, font file bytes, epub page HTML and resource bytes, the server log zip, and the stats file-extension CSV.
Multipart uploads on Cbl, Font, Theme, and Upload. The tool sends JSON and cannot attach a file part.
JSON image lookups and the rest of Upload stay in the registry.
What this is not
This is not a Kavita+ client and it will not call kavitareader.com. It does not download archives, serve OPDS, stream pages, or speak KOReader or Tachiyomi sync. It does not copy Kavita source. HTTP mode is an unauthenticated localhost transport for your own process.
Live check result: 43 checks passed, failed=0, against a real local Kavita 0.9.1.4 (about 22 of 453 ops live). See LIVE-CHECK.md for exact coverage.
License
MIT, see LICENSE. This is an independent, unofficial connector and is not endorsed by the Kavita project or its owners.
The upstream kavita.openapi.json comes from a GPL-3.0 project, so it is not shipped here. src/operations.ts was generated from it, and tests fall back to a route-only fixture in test/fixtures/. To regenerate, download the spec from the upstream project into the repo root (it is gitignored) and run node scripts/gen-operations.mjs.
Available Tools
12 toolskavita_chapterADestructive
kavita_chapter covers the chapter toolset (5 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive, credential, or exposure actions add an extra warning in the preview and here: delete, scan, analyze, refresh, cache clear, cleanup, user or role changes, Auth Key create or revoke, password reset, settings, license, scrobbling tokens, OAuth or OIDC, and email. Actions: delete, get, get_chapter_detail_plus, post_delete_multiple, post_update.
Inputs: action (required), body, query, params, +2 more.
kavita_collectionADestructive
kavita_collection covers the collection toolset (12 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive, credential, or exposure actions add an extra warning in the preview and here: delete, scan, analyze, refresh, cache clear, cleanup, user or role changes, Auth Key create or revoke, password reset, settings, license, scrobbling tokens, OAuth or OIDC, and email. Actions: delete, get, get_all_series, get_mal_stacks, get_name_exists, get_single, post_delete_multiple, post_import_stack, post_promote_multiple, post_update, post_update_for_series, post_update_series.
Inputs: action (required), body, query, params, +2 more.
kavita_libraryADestructive
kavita_library covers the library toolset (23 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive, credential, or exposure actions add an extra warning in the preview and here: delete, scan, analyze, refresh, cache clear, cleanup, user or role changes, Auth Key create or revoke, password reset, settings, license, scrobbling tokens, OAuth or OIDC, and email. Actions: delete_delete, delete_delete_multiple, get, get_jump_bar, get_libraries, get_list, get_metadata_enabled_libraries, get_metadata_providers, get_name_exists, get_scrobble_enabled_libraries, get_type, get_user_libraries, post_copy_settings_from, post_create, post_grant_access, post_has_files_at_root, post_refresh_metadata, post_refresh_metadata_multiple, post_scan, post_scan_all, post_scan_folder, post_scan_multiple, post_update.
Inputs: action (required), body, query, params, +2 more.
kavita_metadataARead-only
kavita_metadata covers the metadata toolset (14 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Actions: get_age_ratings, get_all_bcp47_languages, get_all_languages, get_genres, get_language_title, get_languages, get_people, get_people_by_role, get_publication_status, get_readinglist_tags, get_series_detail_plus, get_tags, post_genres_with_counts, post_tags_with_counts.
Inputs: action (required), body, query, params, +1 more.
kavita_personA
kavita_person covers the person toolset (10 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Actions: get, get_chapters_by_role, get_roles, get_search, get_series_known_for, post_all, post_fetch_cover, post_merge, post_update, post_valid_alias.
Inputs: action (required), body, query, params, +2 more.
kavita_readinglistADestructive
kavita_readinglist covers the readinglist toolset (27 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive, credential, or exposure actions add an extra warning in the preview and here: delete, scan, analyze, refresh, cache clear, cleanup, user or role changes, Auth Key create or revoke, password reset, settings, license, scrobbling tokens, OAuth or OIDC, and email. Actions: delete, get, get_all_people, get_info, get_items, get_lists_for_chapter, get_lists_for_series, get_name_exists, get_next_chapter, get_people, get_prev_chapter, post_all, post_create, post_delete_item, post_delete_multiple, post_export_as_cbl, post_lists, post_promote_multiple, post_regenerate_cover, post_remove_read, post_update, post_update_by_chapter, post_update_by_multiple, post_update_by_multiple_series, post_update_by_series, post_update_by_volume, post_update_position.
Inputs: action (required), body, query, params, +2 more.
kavita_searchARead-only
kavita_search covers the search toolset (4 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Actions: get_chapters_by_series, get_search, get_series_for_chapter, get_series_for_mangafile.
Inputs: action (required), body, query, params, +1 more.
kavita_seriesADestructive
kavita_series covers the series toolset (33 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive, credential, or exposure actions add an extra warning in the preview and here: delete, scan, analyze, refresh, cache clear, cleanup, user or role changes, Auth Key create or revoke, password reset, settings, license, scrobbling tokens, OAuth or OIDC, and email. Actions: delete, get, get_age_rating, get_all_related, get_chapter, get_currently_reading, get_external_series_detail, get_match_info, get_metadata, get_next_expected, get_related, get_series_by_collection, get_series_detail, get_series_with_annotations, get_volume, get_volumes, post_all_v2, post_analyze, post_delete_multiple, post_dont_match, post_match, post_metadata, post_on_deck, post_recently_added_v2, post_recently_updated_series, post_refresh_metadata, post_remove_from_on_deck, post_scan, post_series_by_ids, post_update, post_update_match, post_update_related, post_v2.
Inputs: action (required), body, query, params, +2 more.
kavita_serverADestructive
kavita_server covers the server toolset (17 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive, credential, or exposure actions add an extra warning in the preview and here: delete, scan, analyze, refresh, cache clear, cleanup, user or role changes, Auth Key create or revoke, password reset, settings, license, scrobbling tokens, OAuth or OIDC, and email. Actions: get_changelog, get_check_for_updates, get_check_out_of_date, get_check_update, get_is_task_running, get_jobs, get_media_errors, get_server_info_slim, post_analyze_files, post_backup_db, post_bust_kavitaplus_cache, post_cleanup, post_cleanup_want_to_read, post_clear_cache, post_clear_media_alerts, post_convert_media, post_sync_themes.
Inputs: action (required), body, query, params, +2 more.
kavita_statsARead-only
kavita_stats covers the stats toolset (33 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Actions: get_avg_time_by_hour, get_day_breakdown, get_device_client_type, get_device_device_type, get_favorite_authors, get_files_added_over_time, get_genre_breakdown, get_most_active_users, get_page_spread, get_pages_per_year, get_popular_decades, get_popular_genres, get_popular_libraries, get_popular_people, get_popular_reading_list, get_popular_series, get_popular_tags, get_reading_activity, get_reading_counts, get_reading_history, get_reading_history_series, get_reading_pace, get_reads_by_month, get_server_count_manga_format, get_server_count_publication_status, get_server_file_breakdown, get_server_stats, get_tag_breakdown, get_total_reads, get_user_read, get_user_stats, get_word_spread, get_words_per_year.
Inputs: action (required), body, query, params, +1 more.
kavita_volumeADestructive
kavita_volume covers the volume toolset (4 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive, credential, or exposure actions add an extra warning in the preview and here: delete, scan, analyze, refresh, cache clear, cleanup, user or role changes, Auth Key create or revoke, password reset, settings, license, scrobbling tokens, OAuth or OIDC, and email. Actions: delete, get, post_multiple, post_update.
Inputs: action (required), body, query, params, +2 more.
kavita_wanttoreadA
kavita_wanttoread covers the wanttoread toolset (4 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Actions: get, post_add_series, post_remove_series, post_v2.
Inputs: action (required), body, query, params, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
The 12 tools split cleanly by resource (library, series, volume, chapter, collection, readinglist, etc.), so the top-level choice is usually obvious. However, actions bleed across resources: chapter lookups appear in kavita_chapter, kavita_series (get_chapter), kavita_search (get_chapters_by_series) and kavita_readinglist, and generic actions like `get`, `delete`, and `get_name_exists` repeat in several tools with different targets. An agent must read descriptions carefully to pick the right tool for cross-cutting queries.
All 12 tool names follow a clean `kavita_<resource>` pattern, making the set easy to scan. The inconsistency is one level down: actions mix HTTP-verb prefixes (`get_`, `post_`, `delete_`), producing oddities like `delete_delete`, `post_all_v2`, and `post_delete_multiple`, which read as leaked route names rather than a deliberate verb_noun convention.
Twelve tools is squarely in the well-scoped range and maps to the natural domain entities of a self-hosted manga/comic server. The heavy lifting is pushed into per-tool `action` parameters, keeping the top-level surface small without collapsing unrelated resources into one god-tool.
Core library lifecycle is well covered: create/update/delete for library, series, volume, chapter, collection, and readinglist, plus search, metadata, people, stats, and server maintenance. Gaps exist around user/role administration, auth keys, settings, scrobbling/OAuth, and email — all referenced in the write-warning boilerplate but with no corresponding toolset — and annotation handling is read-only.
Maintenance
Related MCP Connectors
Read-only MCP server for verified book recommendations and reading lists.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables conversational management of a Calibre ebook library via MCP, including search, metadata editing, adding, converting, deduplicating, removing, and emailing books with human-in-the-loop safety.1MIT
- AlicenseAqualityCmaintenanceMCP server exposing Komga's REST API as tools for browsing and managing comic, manga, BD, magazine, and ebook libraries.8MIT
- AlicenseBqualityCmaintenanceMCP server that exposes the Bookshelf (Readarr fork) v1 REST API as tools, allowing an LLM to read and manage authors, books, book files, editions, series, download queue, history, indexers, import lists, custom formats, tags, commands, and system status, with full read/write access and destructive tools flagged.15MIT
- AlicenseAqualityCmaintenanceEnables managing a self-hosted media library through its HTTP API, with scoped toolsets, confirm-gated writes, dry-run previews, and read caching. Supports libraries, items, collections, playlists, podcasts, sessions, stats, tags, genres, and administrative operations.13MIT