komga
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., "@komga list my Komga libraries"
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.
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: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": {
"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=... \
komgaDo not put keys in the image.
Regenerate the registry after an OpenAPI bump.
npm run gen:operationsscripts/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 |
| Required. Self-hosted origin, |
| API key from User settings. Sent as the |
| Optional login, usually the account email. Set together with |
| Password for that login. Sent as HTTP basic auth. Redacted everywhere. |
| 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 a secret. |
|
|
| 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 |
| 9 | yes |
series |
| 16 | yes |
books |
| 16 | yes |
collections |
| 5 | yes |
readlists |
| 5 | yes |
referential_metadata |
| 13 | yes |
management |
| 1 | yes |
announcements |
| 2 | no |
api_keys |
| 3 | no |
book_pages |
| 1 | no |
book_poster |
| 5 | no |
claim |
| 2 | no |
client_settings |
| 6 | no |
collection_poster |
| 4 | no |
collection_series |
| 1 | no |
current_user |
| 3 | no |
deprecated |
| 13 | no |
duplicate_pages |
| 6 | no |
file_system |
| 1 | no |
fonts |
| 1 | no |
history |
| 1 | no |
import |
| 3 | no |
mihon |
| 4 | no |
oauth2 |
| 1 | no |
readlist_books |
| 3 | no |
readlist_poster |
| 4 | no |
releases |
| 1 | no |
series_poster |
| 4 | no |
server_settings |
| 2 | no |
sync_points |
| 1 | no |
tasks |
| 1 | no |
user_session |
| 3 | no |
users |
| 7 | no |
web_pub_manifest |
| 7 | no |
Available Tools
7 toolskomga_booksADestructive
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_collectionsADestructive
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_librariesADestructive
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_managementBRead-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_readlistsBDestructive
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_metadataARead-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_seriesADestructive
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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Remote MCP server exposing SMI Aware tools, resources, and skills over Streamable HTTP.
Query SEC EDGAR filings, XBRL financials, and company data via MCP. STDIO or Streamable HTTP.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Remote MCP server for AIStoryHub: stories, chapters, story bible, Voiceprints, AI generation.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server exposing Komga's REST API as tools for browsing and managing comic, manga, BD, magazine, and ebook libraries.8MIT
- AlicenseNot gradedqualityBmaintenanceGives 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.6Apache 2.0
- AlicenseDqualityCmaintenanceEnables 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.40MIT
- AlicenseAqualityCmaintenanceConnects 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.5MIT