Skip to main content
Glama

@hushvert/mcp

npm license

A file-conversion tool for your AI agent.

@hushvert/mcp is a Model Context Protocol server that gives an AI coding agent (Claude Code, Cursor, Cline, Zed, and any other MCP host) a convert_file tool over the hushvert hosted API. When a task needs a conversion a browser cannot do - office documents to PDF, PDF to Word, large video transcodes - the agent converts the file in one tool call, and the result is written next to the input. No upload code, no polling, no glue.

It is a thin client over the hushvert hosted API. For the conversions that DO run in a browser (images, HEIC, archives, audio, small video, PDF page ops), use the free, open-source @hushvert/engine package instead - this server will refuse those and point you there.

Demo

A real run in Claude Code, recorded live and not sped up: ask, and report.pdf is written next to the input. The whole turn took 23 seconds, of which the conversion itself was about 7.

Claude Code converting report.docx to PDF with the hushvert MCP server

The recording starts Claude Code with only this server loaded (--strict-mcp-config) so nothing unrelated is on screen. The tape that produced it is assets/demo.tape, if you want to reproduce it.

Related MCP server: mcp-document-converter

Claude Code can already convert files. Why this?

Because it can only convert what your machine can convert, and when it cannot, it does not fail loudly.

Ask any coding agent to turn report.docx into a PDF. If LibreOffice is installed, it will shell out to soffice, do a good job, and you do not need this server. If LibreOffice is not installed, and it is not there by default on macOS, on Windows, or in a typical CI image, the usual fallback is pandoc. Pandoc does not really convert a Word document. It reads the text into its own AST, hands that to LaTeX, and LaTeX typesets a new document. You get a PDF. The agent reports success. Nobody opens the file.

Here is the same report.docx down both paths:

The same Word document converted by pandoc and by hushvert, side by side

Same words, different document. Every font in the pandoc PDF is Latin Modern, LaTeX's default. The heading color is gone, the table lost its Word styling, and the title moved into a centered LaTeX title block. pdffonts on the two outputs:

pandoc     LMRoman17-Regular, LMRoman12-Bold, LMRoman10-Italic, ...
hushvert   Carlito-Regular, Carlito-Bold, Carlito-Italic

Carlito is metric-compatible with Calibri, which is what the document actually asked for. Latin Modern is not.

So, honestly:

  • If LibreOffice is installed and your agent reaches for it, you do not need this server. That is a real answer, and it is the right one for a lot of people.

  • If it is not installed, this is one line of config instead of a 281 MB download, and it behaves the same on your laptop, in CI, in a container, and on a machine you are not allowed to install software on.

  • Name the tool if it matters. On a machine that had both this server and pandoc available, we asked the plain way ("convert report.docx to PDF") twice: Claude Code used convert_file once and pandoc the other time, and the two runs produced the two documents above. Which tool an agent reaches for is its call, not ours. "Convert report.docx to PDF with hushvert" pins it.

Install

Get an API key at hushvert.com/developers/keys (sign-in is a one-time email code; keys require a confirmed email), then add the server to your agent's MCP config.

Claude Code - one line, no file to edit:

claude mcp add hushvert -e HUSHVERT_API_KEY=hv_live_your_key_here -- npx -y @hushvert/mcp

Cursor, Cline, Zed, and other MCP hosts (or Claude Code, if you prefer a committed project config) - add this block to the host's MCP config (.mcp.json, .cursor/mcp.json, and so on):

{
  "mcpServers": {
    "hushvert": {
      "command": "npx",
      "args": ["-y", "@hushvert/mcp"],
      "env": { "HUSHVERT_API_KEY": "hv_live_your_key_here" }
    }
  }
}

If that file is committed, do not put the key in it. Claude Code expands environment variables in an MCP config, so use "HUSHVERT_API_KEY": "${HUSHVERT_API_KEY}" and keep the real key in your shell. Other hosts vary; check yours before committing.

Then ask your agent: "convert report.docx to PDF with hushvert." Naming the server is worth the two extra words: if your machine has a local converter, the agent may reach for that instead, and for office documents the result is usually worse. See above.

Tools

Tool

What it does

convert_file

Convert a local file to another format. Reads the input, runs the conversion, writes the output, returns the path.

convert_poll

Finish a long conversion (large video) that was still running when convert_file returned.

list_formats

List the conversions the hosted API supports (the server-only pairs).

check_usage

Show free conversions remaining, credit balance, and the current billing window.

convert_file

input_path       (required) path to the source file
to               (required) target format, e.g. "pdf", "docx", "mp4"
from             (optional) source format; inferred from the extension otherwise
output_path      (optional) where to write; defaults beside the input. Required to overwrite.
wait_seconds     (optional) max seconds to wait before handing back a jobId to poll. Default 120.
idempotency_key  (optional) makes a retried conversion safe (same job, charged once)

Returns { output_path, jobId, pair, bytesIn, bytesOut, status }. If the job is still running after wait_seconds (typical for large video), it returns { jobId, status: "processing", resumeWith: "convert_poll" }; call convert_poll with the jobId and an output_path to finish.

What it converts

The server-only formats a browser cannot do:

  • Office to PDF: docx, pptx, xlsx, doc, ppt, xls, odt, ods, odp, rtf, html to pdf

  • PDF to Word: pdf to docx

  • Document interchange: md, html, epub, latex, rst, docx (via pandoc)

  • Video: mov, mkv, avi, webm to mp4 (and mp4 to gif)

Call list_formats for the live list. Everything else (images, HEIC, archives, audio, small video, PDF page ops) runs free, client-side, in @hushvert/engine.

Configuration

Env var

Default

Purpose

HUSHVERT_API_KEY

(required)

Your hv_live_ developer key.

HUSHVERT_API_BASE

https://hushvert.com

API base URL (for self-host / staging).

HUSHVERT_DEFAULT_WAIT_SECONDS

120

Default poll budget for convert_file.

HUSHVERT_MAX_JOBS_PER_SESSION

unlimited

Client-side cap on conversions per server run (a guard against runaway loops).

HUSHVERT_ALLOWED_DIR

unset

If set, the server only reads/writes files under this directory.

Billing and privacy

Conversions are billed per use against your account: a free monthly allowance, then credits. check_usage shows your remaining allowance and balance at any time - have your agent check it before a large batch. The hosted API processes the server-only formats that genuinely cannot run in a browser; for everything else the file never leaves the device via the open-source engine. See hushvert.com/for-developers.

Security

The API key is read from the environment, never logged, and never returned in a tool result or error. See SECURITY.md.

License

MIT

Available Tools

4 tools
check_usageCheck hushvert usage and balanceA

Report this account hushvert usage: free monthly conversions remaining, credit balance, and the current billing window. Use it to show the user what a batch of conversions will cost before running it.

Inputs: no named parameters.

convert_fileConvert a file with hushvertA

Convert a local file to another format using the hushvert hosted API. Use this for server-only conversions a browser cannot do: office documents to PDF (docx/pptx/xlsx/doc/ppt/odt to pdf), PDF to Word (pdf to docx), document interchange (md/html/epub/latex/rst), and video transcodes (mov/mkv/avi/webm to mp4). Reads the input file, runs the conversion, and writes the result locally. Returns the output path. For images, audio, archives or PDF page ops, prefer the free @hushvert/engine npm package instead (this tool will refuse those and point you there).

Inputs: to (required), input_path (required), from, output_path, +2 more.

convert_pollFinish a long hushvert conversionA

Resume a conversion that was still running when convert_file returned (typically a large video). Poll the job by id and, when done, write the result to output_path.

Inputs: jobId (required), output_path, wait_seconds.

list_formatsList hushvert server conversionsA

List the conversions the hushvert hosted API supports (the server-only pairs). Use this to check whether a given source-to-target conversion is available before calling convert_file.

Inputs: from.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct purpose: usage checking, file conversion, polling async jobs, and listing formats. No overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with underscores (check_usage, convert_file, convert_poll, list_formats), making them predictable.

    Tool Count5/5

    4 tools are well-scoped for a file conversion server, covering the essential operations without unnecessary bloat.

    Completeness4/5

    The tool set covers the core conversion workflow: checking usage, listing supported formats, converting, and polling async results. Missing a cancel conversion tool but that's a minor gap.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables document conversion between various formats (Markdown, DOCX, HTML, PDF, etc.) using Pandoc, allowing AI agents to request conversions via natural language.
      7
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to inspect and convert PDF, PowerPoint, Excel, and many other file formats into clean, structured Markdown, with chunking support for long documents.
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI agents to convert documents, images, and data files across 50+ format pairs and to run PDF/image operations such as merge, split, compress, rotate, protect, unlock, extract text, and resize or compress images. Files are passed URL-in and returned URL-out (or saved locally in stdio mode), with tools for checking credits and generating Stripe checkout or billing-portal links.
      18
      37 PyPI
      MIT