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

Related MCP server: access-calibre

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.

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.

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

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