komga-mcp

A small, read-only Model Context Protocol (MCP) server that exposes your Komga reading data to any MCP-compatible client over Streamable HTTP.

It is intentionally minimal and safe: it can only read from Komga. There is no tool that writes progress, edits metadata, deletes, downloads, scans, or issues arbitrary API calls.

Tools

The server advertises exactly four tools:

Every response is a normalized JSON payload — never a raw Komga dump, never file paths or device identifiers.

Related MCP server: mealie-mcp

HTTP endpoints

Inbound requests to /mcp and /ready require Authorization: Bearer <MCP_BEARER_TOKEN>.

Configuration

Set via environment variables (see .env.example):

Generate a strong bearer token, for example: openssl rand -hex 32.

Run with Docker

cp .env.example .env   # then edit .env with real values
docker run --rm --env-file .env -p 8101:8000 ghcr.io/pierrec18/komga-mcp:0.1.0

Or with Compose — see compose.example.yaml. The image runs as a non-root user and is compatible with a read-only root filesystem.

Run from source

npm ci
npm run build
KOMGA_URL=http://localhost:25600 \
KOMGA_API_KEY=... \
MCP_BEARER_TOKEN=... \
npm start

Connecting an MCP client

Point any MCP client at the Streamable HTTP endpoint and pass the bearer token. Example with the official TypeScript SDK:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:8101/mcp"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.MCP_BEARER_TOKEN}` } } },
);
const client = new Client({ name: "my-client", version: "1.0.0" });
await client.connect(transport);
console.log(await client.listTools());

This server is not tied to any particular client or agent framework.

Development

npm ci
npm run lint       # ESLint
npm run typecheck  # tsc --noEmit
npm test           # vitest (runs against a fake Komga; never your real instance)
npm run build      # emit dist/

Security

See SECURITY.md. In short: read-only by design, bearer-protected, secrets never logged, upstream errors sanitized, timeouts and bounded limits on everything.

License

MIT