Skip to main content
Glama

komga

MCP connector for a self-hosted Komga server (v1.29.2). It speaks the HTTP API over stdio and over stateless Streamable HTTP on localhost.

Komga is MIT-licensed software. This connector does not copy that code. It only calls the HTTP API on the server you configure. It is not affiliated with Komga.

The spec file komga.openapi.json is copied from Komga 1.29.2 (MIT, gotson/komga). It has 177 operations. This connector covers 155 of them in 34 tools. It leaves out 22 endpoints that return files, images, page bytes, font bytes, or multipart uploads. 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. KOMGA_URL is required.

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": {
    "komga": {
      "command": "node",
      "args": ["/workspace/connectors/komga/dist/index.js"],
      "env": {
        "KOMGA_URL": "http://127.0.0.1:25600",
        "KOMGA_API_KEY": "...",
        "KOMGA_ALLOW_WRITES": "false",
        "KOMGA_TOOLSETS": "libraries,series,books,collections,readlists,referential_metadata,management"
      }
    }
  }
}

You can set KOMGA_USERNAME and KOMGA_PASSWORD instead of KOMGA_API_KEY. The connector then sends HTTP basic auth.

Docker (HTTP, no authentication, keep it on localhost):

docker build -t komga .
docker run -p 127.0.0.1:3000:3000 \
  -e KOMGA_URL=http://127.0.0.1:25600 \
  -e KOMGA_API_KEY=... \
  komga

Do not put keys in the image.

Regenerate the registry after an OpenAPI bump.

npm run gen:operations

scripts/live-check.mjs talks to a real server over stdio. It needs KOMGA_URL and either KOMGA_API_KEY or KOMGA_USERNAME plus KOMGA_PASSWORD. It can also claim a fresh server when KOMGA_CLAIM=true. It sets KOMGA_TOOLSETS=all. Gated writes run only when KOMGA_ALLOW_WRITES=true. It prints pass or fail lines only. This workspace does not start Komga.

Related MCP server: mcp-calibre

Config

Variable

Meaning

KOMGA_URL

Required. Self-hosted origin, http or https, no userinfo, query, or hash. Example http://127.0.0.1:25600.

KOMGA_API_KEY

API key from User settings. Sent as the X-API-Key header.

KOMGA_USERNAME

Optional login, usually the account email. Set together with KOMGA_PASSWORD when no API key is set.

KOMGA_PASSWORD

Password for that login. Sent as HTTP basic auth. Redacted everywhere.

KOMGA_ALLOW_WRITES

Must be the literal true before a confirmed write is sent.

KOMGA_TOOLSETS

Comma list of toolsets, or all. Default is the read-focused set below.

KOMGA_PER_MINUTE

Local request budget. Default 30. Cache hits do not spend it.

KOMGA_TIMEOUT_MS

Upstream timeout. Default 20000.

KOMGA_CACHE_TTL_SEC

Read cache TTL. Default 60. Writes clear the cache.

KOMGA_CONTACT

Contact token in the User-Agent. Must not contain a secret.

MCP_TRANSPORT

stdio or http. --http overrides.

PORT

HTTP port. Default 3000.

Invalid values are reported by field name and issue code. The rejected value is not included. API keys, passwords, and emails are redacted in logs, errors, tool results, thrown messages, and URLs.

Auth is X-API-Key when KOMGA_API_KEY is set. Otherwise it is Authorization: Basic from KOMGA_USERNAME and KOMGA_PASSWORD. The connector never puts credentials in the API URL.

Safety

GET is a read. POST, PUT, PATCH, and DELETE are writes, except a reviewed list of POST queries in READ_POST_PATHS (book list, series list, series groups, filesystem listing). GET /api/logout and GET /api/v1/login/set-cookie are writes (GET_SIDE_EFFECT_PATHS). Anything not on the read list stays a write.

A write needs confirm: true as a boolean and KOMGA_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, analyze, refresh, trash empty, user changes, API key create and revoke, password change, settings, session, and claim.

API key create returns the key once, with a shown-only-once note. Later list and get calls redact it. User email, password, key, and token fields 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.

File downloads, poster and page images, raw page bytes, font files, CSS, epub resources, and multipart poster uploads are not exposed.

Tools

Default KOMGA_TOOLSETS publishes 7 tools. KOMGA_TOOLSETS=all publishes 34 tools (155 operations, 91 reads and 64 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

libraries

komga_libraries

9

yes

series

komga_series

16

yes

books

komga_books

16

yes

collections

komga_collections

5

yes

readlists

komga_readlists

5

yes

referential_metadata

komga_referential_metadata

13

yes

management

komga_management

1

yes

announcements

komga_announcements

2

no

api_keys

komga_api_keys

3

no

book_pages

komga_book_pages

1

no

book_poster

komga_book_poster

5

no

claim

komga_claim

2

no

client_settings

komga_client_settings

6

no

collection_poster

komga_collection_poster

4

no

collection_series

komga_collection_series

1

no

current_user

komga_current_user

3

no

deprecated

komga_deprecated

13

no

duplicate_pages

komga_duplicate_pages

6

no

file_system

komga_file_system

1

no

fonts

komga_fonts

1

no

history

komga_history

1

no

import

komga_import

3

no

mihon

komga_mihon

4

no

oauth2

komga_oauth2

1

no

readlist_books

komga_readlist_books

3

no

readlist_poster

komga_readlist_poster

4

no

releases

komga_releases

1

no

series_poster

komga_series_poster

4

no

server_settings

komga_server_settings

2

no

sync_points

komga_sync_points

1

no

tasks

komga_tasks

1

no

user_session

komga_user_session

3

no

users

komga_users

7

no

web_pub_manifest

komga_web_pub_manifest

7

no

Available Tools

7 tools
komga_booksA
Destructive

komga_books covers the books toolset (16 operations). Auth is the X-API-Key header, or HTTP basic auth from KOMGA_USERNAME and KOMGA_PASSWORD. Self-hosted Komga only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KOMGA_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, trash empty, user or role changes, API key create or revoke, password change, settings, session, and claim. Actions: delete_file, delete_read_progress, get, get_book_id, get_duplicates, get_latest, get_next, get_ondeck, get_previous, get_readlists, patch_metadata, patch_metadata_book_id, patch_read_progress, post_analyze, post_list, post_metadata_refresh.

Inputs: action (required), body, query, params, +2 more.

komga_collectionsA
Destructive

komga_collections covers the collections toolset (5 operations). Auth is the X-API-Key header, or HTTP basic auth from KOMGA_USERNAME and KOMGA_PASSWORD. Self-hosted Komga only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KOMGA_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, trash empty, user or role changes, API key create or revoke, password change, settings, session, and claim. Actions: delete, get, get_id, patch, post.

Inputs: action (required), body, query, params, +2 more.

komga_librariesA
Destructive

komga_libraries covers the libraries toolset (9 operations). Auth is the X-API-Key header, or HTTP basic auth from KOMGA_USERNAME and KOMGA_PASSWORD. Self-hosted Komga only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KOMGA_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, trash empty, user or role changes, API key create or revoke, password change, settings, session, and claim. Actions: delete, get, get_library_id, patch, post, post_analyze, post_empty_trash, post_metadata_refresh, post_scan.

Inputs: action (required), body, query, params, +2 more.

komga_managementB
Read-only

komga_management covers the management toolset (1 operations). Auth is the X-API-Key header, or HTTP basic auth from KOMGA_USERNAME and KOMGA_PASSWORD. Self-hosted Komga only. action help with target returns one action's parameters. Actions: get_actuator_info.

Inputs: action (required), body, query, params, +1 more.

komga_readlistsB
Destructive

komga_readlists covers the readlists toolset (5 operations). Auth is the X-API-Key header, or HTTP basic auth from KOMGA_USERNAME and KOMGA_PASSWORD. Self-hosted Komga only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KOMGA_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, trash empty, user or role changes, API key create or revoke, password change, settings, session, and claim. Actions: delete, get, get_id, patch, post.

Inputs: action (required), body, query, params, +2 more.

komga_referential_metadataA
Read-only

komga_referential_metadata covers the referential_metadata toolset (13 operations). Auth is the X-API-Key header, or HTTP basic auth from KOMGA_USERNAME and KOMGA_PASSWORD. Self-hosted Komga only. action help with target returns one action's parameters. Actions: get_age_ratings, get_authors, get_authors_names, get_authors_roles, get_genres, get_languages, get_notable_entities, get_notable_entities_kinds, get_notable_entities_names, get_publishers, get_series_release_years, get_sharing_labels, get_tags.

Inputs: action (required), body, query, params, +1 more.

komga_seriesA
Destructive

komga_series covers the series toolset (16 operations). Auth is the X-API-Key header, or HTTP basic auth from KOMGA_USERNAME and KOMGA_PASSWORD. Self-hosted Komga only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KOMGA_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, trash empty, user or role changes, API key create or revoke, password change, settings, session, and claim. Actions: delete_file, delete_read_progress, get, get_alphabetical_groups, get_books, get_collections, get_latest, get_new, get_series_id, get_updated, patch_metadata, post_analyze, post_list, post_list_alphabetical_groups, post_metadata_refresh, post_read_progress.

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

    A3.7/5.0

    Scored across 7 tools

    Disambiguation4/5

    Tools are split cleanly by Komga resource (books, series, collections, readlists, libraries, referential metadata, management), so the main boundaries are clear. However, collections and readlists have almost identical action shapes, and books/series both expose overlapping read-progress and listing actions, which could cause occasional misselection.

    Naming Consistency5/5

    Every tool follows the same komga_<resource> snake_case convention, with plural resource names except for the clearly named referential_metadata and management sets. There is no mixing of camelCase or inconsistent verb/noun patterns at the tool level.

    Tool Count4/5

    Seven tools is a reasonable scoping for a Komga server and keeps the top-level surface manageable. The only slight imbalance is komga_management, which contains a single actuator-info operation and feels underfilled compared with the other resource toolsets.

    Completeness4/5

    Core library management coverage is strong: books, series, collections, readlists, and libraries all support relevant read/write/lifecycle operations. There are still notable gaps around administrative surfaces mentioned in the warnings—users, roles, API keys, sessions, settings, password changes, and claims—which have no corresponding toolset.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives MCP clients read-only access to a local Calibre library, enabling metadata search with Calibre query syntax, BM25 full-text search across EPUB/PDF/MOBI/LIT, chapter and page reading, highlights, notes, reading progress, and duplicate detection. It runs over stdio or Streamable HTTP with bearer authentication, using direct SQLite connections so it keeps working while the Calibre GUI is open.
      6
      Apache 2.0
    • A
      license
      D
      quality
      C
      maintenance
      Enables secure, configurable access to one or more Syncthing instances over MCP, with read-only defaults and opt-in write, destructive, and administrative operations. Supports stdio and authenticated Streamable HTTP transports, typed tools, bounded responses, and multi-instance configuration.
      40
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Connects MCP clients to a self-hosted photo library through its REST API, exposing assets, albums, people, search, and optional administrative toolsets with read-only defaults and confirm-gated writes. It supports stdio and localhost Streamable HTTP transports.
      5
      MIT