kabuk-mcp

An MCP server that converts documents to token-efficient Markdown. PDF, DOCX, PPTX, XLSX, HTML, EPUB, Markdown and plain text in. Clean Markdown out, with the token saving reported alongside it.

Runs entirely on your machine. Nothing is uploaded, no model is involved in the conversion, and no tool touches the network.

Install

You do not run it directly. An MCP client launches it and talks JSON-RPC over stdio. Add it to your client's config:

{
  "mcpServers": {
    "kabuk": { "command": "npx", "args": ["-y", "kabuk-mcp"] }
  }
}

Node 20 or newer.

After that it is invisible. Ask for a summary of a contract and drop in the PDF; the model calls kabuk_convert_file, gets Markdown back, and can tell you what the conversion saved.

Tools

kabuk_convert_file

Convert a local file. Takes an absolute path, plus optional frontmatter (prepend a YAML block with title, source and format), revisions for DOCX (accept drops deletions, show strikes them through — default accept), and maxTableRows for spreadsheets (default 1000).

kabuk_convert_text

Convert markup you already have, without reading a file. Takes text, plus optional format (html, md, txt — detected from content when omitted) and baseUrl, which resolves relative links in HTML.

kabuk_count_tokens

Count what a string costs without converting it. Takes text and an optional model (claude, gpt, gemini, generic). Answers are labelled estimated or exact and the label is not decorative — see below.

What it saves

Nothing comes back larger than it went in. If a conversion would cost more tokens than the plain text of the same document, the plain text is returned instead, with a warning saying structure was dropped to keep that guarantee.

Beyond that, the reduction is a property of the document rather than the converter. It tracks how much of the source was never content, so it spans roughly 9 to 92 percent on web pages depending on how much navigation the page carries. A PDF repeating a running header across forty pages saves 11 percent.

Office formats run from zero to 6 percent. Little in them was ever non-content — no navigation, no chrome — so there is little to strip. A numeric spreadsheet saves 4 to 6 and keeps its columns; a text-heavy sheet, a DOCX or a deck breaks even at zero and returns as plain text, because adding headings would have cost more than it saved.

Run pnpm bench in the repo for current numbers rather than trusting this paragraph.

Estimates are labelled

Token counts come from a segmenting heuristic that lands within roughly five percent on mixed content, and every count says estimated when the heuristic ran. exact appears only when a real BPE has been registered, which this server does not do. The savings figure is the one number this tool is sold on, so it is never presented as more precise than it is.

Limits

• Scanned PDFs. A PDF with no text layer is detected and reported, not silently returned empty. OCR is not shipped yet, so there is nothing to fall back to.
• Encrypted PDFs fail with a sentence rather than a stack trace.
• No network tool. Converting a URL would mean downloading it, and a download is a network call. Fetch the page with something else and hand the markup to kabuk_convert_text.

Related

• kabuk-core — the engine, with no platform dependencies
• kabuk-epub — the EPUB converter

License

Apache-2.0 · Blu Signal Labs