komga-mcp

Part of the arr-mcps collection. MCP server exposing Komga's REST API as tools for browsing and managing comic, manga, BD, magazine, and ebook libraries. It is built with FastMCP.

Install

Download a wheel from the latest release and install it as a uv tool:

uv tool install komga_mcp-*.whl

Register it with Claude Code:

claude mcp add komga \
  --env KOMGA_URL=https://your-komga-host \
  --env KOMGA_API_KEY=<api-key> \
  -- komga-mcp

From source

uv sync
cp .env.example .env

claude mcp add komga \
  --env KOMGA_URL=https://your-komga-host \
  --env KOMGA_API_KEY=<api-key> \
  -- uv run --directory /path/to/komga-mcp komga-mcp

Configuration

Komga API keys are created in the Komga user settings. The key is sent as X-API-Key on every request. The server does not accept credentials supplied by an MCP tool call.

Env var	Required	Default
KOMGA_URL	yes	-
KOMGA_API_KEY	yes	-
KOMGA_VERIFY_TLS	no	true

KOMGA_URL is the server root, without /api; the client adds the documented /api/v1 and /api/v2 paths itself. Set KOMGA_VERIFY_TLS=false only when a self-signed certificate is intentional.

Tools

8 resource-scoped tools, each covering multiple Komga REST endpoints (81 total) via an operation parameter. Call a tool with operation set to one of its listed operations (the function names below, e.g. list_libraries) and an arguments dict matching that operation's parameters — the tool's own description (visible to your MCP client) lists every operation, its signature, and a one-line doc, including any "Requires ADMIN" notes. Image, file-download, page-stream, and multipart ComicRack endpoints are intentionally excluded.

Tool	Operations	Kind	Covers
komga_libraries	9	reads + writes	Libraries: list, get, create, update, delete, scan, analyze, refresh metadata, empty trash
komga_series	13	reads + writes	Series: search, get, collections, latest/new/updated, thumbnails, metadata, analyze, read progress
komga_books	16	reads + writes	Books: search, get, pages, next/previous, readlists, thumbnails, latest/ondeck/duplicates, metadata, analyze, read progress
komga_collections	6	reads + writes	Collections: list, get, series, create, update, delete
komga_readlists	8	reads + writes	Readlists: list, get, books, next/previous book, create, update, delete
komga_referential_metadata	10	read-only	Authors, tags, genres, publishers, languages, age ratings, sharing labels, release years
komga_users_api_keys	12	reads + writes	whoami, users CRUD, passwords, API keys, auth activity
komga_server	7	reads + writes	Server info, settings, claim status, history, tasks, filesystem

Example: komga_libraries(operation="scan_library", arguments={"library_id": "l1"}).

Search conditions

search_series, search_books, and search_series_alphabetical_groups send a JSON body containing fullTextSearch and an optional recursive condition. Pagination is sent as query parameters (page, size, repeated sort, and unpaged). For example:

{
  "fullTextSearch": "berserk",
  "condition": {
    "allOf": [
      {"genre": {"operator": "contains", "value": "action"}},
      {"readStatus": {"operator": "is", "value": "UNREAD"}}
    ]
  }
}

Use anyOf for OR and allOf for AND. String operators include is, isNot, beginsWith, contains, endsWith, and their negative forms. Boolean fields use isTrue or isFalse; date fields use after, before, isInTheLast, isNotInTheLast, isNull, or isNotNull.

Metadata patches use Komga's normal semantics: omit a field to leave it alone, or send null to unset it. Read progress accepts page and/or completed.

Development

make help

Command	Does
make sync	Run uv sync
make test	Run the offline test suite
make test-integration	Run live tests (needs KOMGA_URL/KOMGA_API_KEY)
make build	Build wheel and sdist into dist/
make bump-patch / bump-minor / bump-major	Bump package version and lockfile
make clean	Remove build artifacts

The release workflow runs tests and publishes wheel and sdist files whenever a v* tag is pushed.