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:http

npm 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:operations

scripts/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: OpenFic MCP

Config

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.

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.