Skip to main content
Glama
si-essence

komga

by si-essence
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

komga_books

Destructive

Manage books in a self-hosted Komga library: retrieve, list duplicates, update metadata or read progress, refresh metadata, and run delete or analyze actions with dry-run previews.

Instructions

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.

Input Schema

NameRequiredDescriptionDefault
bodyNoJSON body for the Komga operation. Secrets are redacted in output.
queryNoOpenAPI query parameters.
actionYesKomga operation to call, or help.
paramsNoOpenAPI path parameters, such as seriesId.
targetNoWith action help, the action whose parameters to describe.
confirmNoSet to the boolean true to execute the write. Omit this field for a dry-run preview. false and the string true are rejected.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing the auth mechanism (X-API-Key or basic auth), the self-hosted-only constraint, the KOMGA_ALLOW_WRITES gate, and the dry-run preview behavior. It also enumerates which actions carry extra destructive warnings (delete, scan, user/role, API key, password, settings, session, claim), which a preview alone would not surface in advance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads auth and write-safety before the action list, and each sentence carries useful information. The trailing action enumeration is somewhat long and partially duplicates the enum, but it aids scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-operation dispatcher with no output schema, the description covers auth, write gating, dry-run semantics, and destructive-action warnings well. It could say more about return shapes or how body/query/params map per action, but the essential calling information is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so parameter descriptions are already solid, but the description adds operational meaning: confirm must be the boolean true (false and string 'true' rejected) and omitting it triggers a preview that sends nothing, plus how target pairs with action help. That workflow context is not fully conveyed by the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States it covers the Komga books toolset (16 operations) and enumerates the available actions, so the verb+resource is clear. It does not explicitly say how it differs from siblings like komga_series or komga_readlists (which even appears as an action here), leaving some ambiguity to be inferred from the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete procedural guidance: use action help with target to inspect a single action, set confirm to execute a write, omit it for a dry-run. It does not name when to pick this tool over a sibling, but the operational context is clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools