Skip to main content
Glama
Sign In
Kavita MCP Connector

Kavita MCP Connector

by si-essence
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

kavita_server

Destructive

Runs self-hosted Kavita server admin tasks: check updates and jobs, inspect media errors, analyze files, back up the database, clear caches, clean up, convert media, and sync themes.

Instructions

kavita_server covers the server toolset (17 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_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, cache clear, cleanup, user or role changes, Auth Key create or revoke, password reset, settings, license, scrobbling tokens, OAuth or OIDC, and email. Actions: get_changelog, get_check_for_updates, get_check_out_of_date, get_check_update, get_is_task_running, get_jobs, get_media_errors, get_server_info_slim, post_analyze_files, post_backup_db, post_bust_kavitaplus_cache, post_cleanup, post_cleanup_want_to_read, post_clear_cache, post_clear_media_alerts, post_convert_media, post_sync_themes.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "kavita_server"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyNoJSON body for the Kavita operation. Secrets are redacted in output.
queryNoOpenAPI query parameters.
actionYesKavita 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.1/5.0
Behavior5/5

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

Goes well beyond the annotations (which only say non-readonly, destructive, open-world): it discloses the auth model (x-api-key header or JWT from KAVITA_USERNAME/KAVITA_PASSWORD), the self-hosted-only constraint, the two-key write gate, the dry-run default that sends nothing, and an explicit enumeration of the destructive/credential/exposure actions that trigger an extra warning. That is exactly the kind of operational context an agent needs before invoking a destructive facade.

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

Conciseness3/5

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

Front-loaded with auth and the write gate, which is the right priority order, but it then re-lists all 17 action names that already appear verbatim in the action enum, and the destructive-action list repeats several of those names. Roughly a third of the text duplicates structured data; the security/warning sentences earn their place, the action roster does not.

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 17-operation facade with nested body/query/params objects and no output schema, the definition covers auth, permissions, write gating, dry-run behavior, and risk tiers — everything needed to invoke it safely. Remaining gaps are minor: nothing about response shape (e.g. what a dry-run preview returns) or error behavior, though the absence of an output schema makes return-value detail less expected.

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 the per-field descriptions already carry the baseline; the tool description still adds workflow semantics the schema cannot: the help/target discovery loop for learning per-action parameters, and the fact that writes require confirm to be the boolean true alongside an environment flag. The body/query/params containers are left entirely to the schema, which is acceptable given full coverage.

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?

Opens with a concrete scope statement ('covers the server toolset (17 operations)') and enumerates the actions, so an agent can tell this is the server-administration facade rather than the library/series/volume/content siblings. It does not explicitly name which sibling to use for non-server work, but the domain split is self-evident from the action prefixes (get_server_info_slim, post_cleanup, post_backup_db).

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 real when/how guidance: use 'action help with target' to discover a single action's parameters, set confirm=true plus KAVITA_ALLOW_WRITES=true to execute, omit confirm for a dry-run that sends nothing. It also flags which action families are destructive and warrant extra caution. It stops short of explicitly routing the agent to sibling tools for non-server operations.

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