@hushvert/mcp

@hushvert/mcp

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.

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 (.mcp.json in your project, or the user config):

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

The same command / args / env block works for Cursor, Cline, Zed, and other MCP hosts. Then ask your agent: "convert report.docx to PDF."

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