hushvert

@hushvert/mcp

AI エージェント向けのファイル変換ツールです。

@hushvert/mcp は、AI コーディングエージェント（Claude Code、Cursor、Cline、Zed、その他すべての MCP ホスト）に、hushvert のホスト型 API 経由で convert_file ツールを提供する Model Context Protocol サーバーです。ブラウザーではできない変換（Office ドキュメントから PDF への変換、PDF から Word への変換、大容量動画のトランスコード）が必要な場合、エージェントは 1 回のツール呼び出しでファイルを変換し、結果を入力ファイルの隣に書き込みます。アップロード用コードも、ポーリングも、つなぎ込みも不要です。

これは、hushvert のホスト型 API を利用する薄いクライアントです。ブラウザーで実行できる変換（画像、HEIC、アーカイブ、音声、小容量動画、PDF ページ操作）には、代わりに無料のオープンソースパッケージ @hushvert/engine を使用してください。このサーバーはそれらの変換を拒否し、適切な利用先を案内します。

デモ

Claude Code での実際の実行を、早送りせずにライブ録画しました。依頼すると、入力ファイルの隣に report.pdf が書き込まれます。ターン全体は 23 秒で、そのうち変換自体にかかった時間は約 7 秒でした。

録画時には、このサーバーだけを読み込んで Claude Code を起動しています（--strict-mcp-config）。そのため、関係のないものは画面に表示されません。再現したい場合は、使用したテープ assets/demo.tape をご覧ください。

Claude Code でもファイルを変換できます。それなのに、なぜこれが必要なのでしょうか？

Claude Code が変換できるのは、お使いのマシンで変換できるものだけで、変換できない場合にも、はっきりと失敗を報告しないことがあるからです。

任意のコーディングエージェントに、report.docx を PDF に変換するよう依頼してみてください。LibreOffice がインストールされていれば、エージェントは soffice を呼び出して適切に変換するので、このサーバーは必要ありません。LibreOffice がインストールされていない場合、また macOS や Windows、一般的な CI イメージには標準で入っていないため、通常は pandoc が代わりに使われます。pandoc は Word ドキュメントを本当の意味で変換するわけではありません。テキストを独自の AST に読み込み、それを LaTeX に渡して、新しいドキュメントを組版します。PDF は生成されます。エージェントは成功を報告します。誰もそのファイルを開きません。

同じ report.docx を、2 つの方法で変換した結果をご覧ください。

文章は同じでも、ドキュメントは異なります。pandoc で作成した PDF のフォントはすべて、LaTeX のデフォルトである Latin Modern です。見出しの色は失われ、表の Word のスタイルも失われ、タイトルは中央揃えの LaTeX のタイトルブロックに移動しています。2 つの出力に対する pdffonts の結果は次のとおりです。

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

Carlito は Calibri とメトリック互換性があります。ドキュメントが実際に指定していたのは Calibri です。一方、Latin Modern は互換性がありません。

率直に言うと、次のとおりです。

• LibreOffice がインストールされていて、エージェントがそれを使うなら、このサーバーは必要ありません。 これは正真正銘の答えであり、多くの方にとって正しい選択です。
• インストールされていない場合は、281 MB をダウンロードする代わりに、設定を 1 行追加するだけです。ノート PC、CI、コンテナー、ソフトウェアのインストールが許可されていないマシンでも、同じように動作します。
• ツールの指定が重要なら、ツール名を明記してください。このサーバーと pandoc の両方が使えるマシンで、簡単な依頼（「report.docx を PDF に変換して」）を 2 回試したところ、Claude Code は一方で convert_file を使い、もう一方では pandoc を使い、上記の 2 つのドキュメントが生成されました。エージェントがどのツールを選ぶかは、私たちではなくエージェント次第です。「hushvert で report.docx を PDF に変換して」と指定すれば、使用するツールを固定できます。

インストール

hushvert.com/developers/keys で API キーを取得し（サインインは一度限りのメールコード方式です。キーの取得には確認済みのメールアドレスが必要です）、サーバーをエージェントの MCP 設定に追加します。

Claude Code - ファイルを編集せずに、1 行で設定できます。

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

Cursor、Cline、Zed、その他の MCP ホスト（または、プロジェクト設定をコミットする場合は Claude Code）- 次のブロックをホストの MCP 設定（.mcp.json、.cursor/mcp.json など）に追加します。

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

このファイルをコミットする場合は、キーを記載しないでください。Claude Code は MCP 設定内の環境変数を展開するため、"HUSHVERT_API_KEY": "${HUSHVERT_API_KEY}" を使い、実際のキーはシェルに保存してください。他のホストの動作は異なる場合があるため、コミットする前に確認してください。

次に、エージェントに「report.docx を hushvert で PDF に変換して」と頼みます。サーバー名を指定するだけのひと手間をかける価値があります。マシンにローカルの変換ツールがある場合、エージェントはそちらを使うことがあり、Office 文書では通常、結果が劣ります。詳しくは上記をご覧ください。

ツール

ツール	機能
convert_file	ローカルファイルを別の形式に変換します。入力を読み取り、変換を実行して出力を書き込み、パスを返します。
convert_poll	convert_file の戻り時にまだ実行中だった長時間の変換（大きな動画）を完了します。
list_formats	ホスト API が対応する変換（サーバーのみで実行される形式の組み合わせ）を一覧表示します。
check_usage	残りの無料変換回数、クレジット残高、現在の請求期間を表示します。

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)

{ output_path, jobId, pair, bytesIn, bytesOut, status } を返します。wait_seconds の経過後もジョブが実行中の場合（大きな動画でよくあります）、{ jobId, status: "processing", resumeWith: "convert_poll" } を返します。完了するには、jobId と output_path を指定して convert_poll を呼び出してください。

変換できる形式

ブラウザーでは処理できない、サーバー専用の形式です。

• Office から PDF：docx、pptx、xlsx、doc、ppt、xls、odt、ods、odp、rtf、html から pdf
• PDF から Word：pdf から docx
• 文書の相互変換：md、html、epub、latex、rst、docx（pandoc 経由）
• 動画：mov、mkv、avi、webm から mp4（および mp4 から gif）

最新の一覧は list_formats を呼び出して確認してください。それ以外のすべて（画像、HEIC、アーカイブ、音声、小さな動画、PDF のページ操作）は、@hushvert/engine を使って無料でクライアント側で処理されます。

設定

環境変数	デフォルト	用途
HUSHVERT_API_KEY	（必須）	開発者用の hv_live_ キーです。
HUSHVERT_API_BASE	https://hushvert.com	API のベース URL（セルフホスト／ステージング用）です。
HUSHVERT_DEFAULT_WAIT_SECONDS	120	convert_file のデフォルトのポーリング待機時間です。
HUSHVERT_MAX_JOBS_PER_SESSION	無制限	サーバーの実行ごとに処理できる変換数のクライアント側の上限です（無限ループを防ぐための保護策です）。
HUSHVERT_ALLOWED_DIR	未設定	設定すると、サーバーはこのディレクトリ配下のファイルのみ読み書きします。

課金とプライバシー

変換はアカウントに対して従量課金されます。毎月の無料利用枠を使い切った後は、クレジットが使用されます。check_usage で、いつでも残りの利用枠と残高を確認できます。大規模な一括処理の前に、エージェントに確認させてください。ホスト API は、ブラウザーで実行できないサーバー専用の形式を処理します。それ以外のファイルは、オープンソースエンジンを介してデバイスの外に送信されることはありません。hushvert.com/for-developersをご覧ください。

セキュリティ

API キーは環境から読み込まれ、ログに記録されたり、ツールの結果やエラーに返されたりすることはありません。SECURITY.mdをご覧ください。

ライセンス

MIT