2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

73.8kスターのMinerU、無料MCPはFlash modeの20ページ止まりだった

2
Posted at

はじめに

RAGパイプラインやAIエージェントに社内資料を読ませようとすると、最初にぶつかるのが「PDFやOffice文書をどうMarkdown化するか」という問題だ。単純なテキスト抽出では表のレイアウトが崩れ、数式は文字化けし、複数カラムのレイアウトは順序がバラバラになる。

この課題に対して、上海AI Lab傘下のOpenDataLabが開発するMinerUは、GitHubで 73.8kスター を集める文書パーサーだ1。筆者が公式ドキュメントとMCPサーバーの設定例を読み解いたところ、CLIとMCPで無料利用できる範囲が非対称であることに気づいた。本記事ではその実態と、ライセンス変更の実務的な意味をまとめる。

この記事で学べること

  • MinerUの技術構成とライセンス変更（AGPLv3→独自ライセンス）が商用利用に与える影響
  • CLIのバックエンド（pipeline / vlm-engine / hybrid-engine 等）の使い分け
  • 公式MCPサーバー経由で使う際に踏む「無料枠」の境界線

対象読者

  • RAGパイプラインやAIエージェントにPDF・Office文書を取り込みたいエンジニア
  • Claude Desktop / Cursor / Windsurf にドキュメント読解を任せたい人

前提環境

  • OS: macOS / Linux
  • Python: 3.10+
  • パッケージ管理: uv

TL;DR

  • MinerUはPDF・DOCX・PPTX・XLSX・画像を高精度でMarkdown/JSON化する文書パーサー。VLM+OCRのデュアルエンジンで109言語のOCRに対応する1
  • ライセンスがAGPLv3から独自の「MinerU Open Source License」（Apache License 2.0ベース）に切り替わった。ただし月間アクティブユーザー1億人、または月商2,000万ドルを超える事業には追加条件が課される2
  • 公式MCPサーバー mineru-open-mcp は、APIキー不要の無料「Flash mode」だと 20ページ・10MBまで という制限があり、CLIのローカル実行とは無料の性質が異なる3

MinerUとは何か

MinerUはPDF・画像・DOCX・PPTX・XLSXを入力として受け取り、LLMが扱いやすいMarkdown/JSON形式に変換するツールだ。README には次のように明記されている。

Support PDF, image, DOCX, PPTX, and XLSX inputs.
— opendatalab/MinerU README

内部にはVLM（Vision Language Model）とOCRを組み合わせたデュアルエンジンを採用し、レイアウト検出にはPaddleOCRベースのモデルを使う。OCR自体は109言語に対応しており、CJK（中国語・日本語・韓国語）を含む複雑なレイアウトの文書でも構造を保ったまま抽出できる点が評価され、スター数を伸ばしてきた1。

ライセンス変更の実務インパクト

MinerUは元々AGPLv3で公開されていたが、2026年6月ごろに独自の「MinerU Open Source License」へ移行した2。このライセンスの本文には次の記載がある。

MinerU is licensed under Apache License 2.0 and is subject to the additional terms below.
— MinerU LICENSE.md

つまりベースはApache License 2.0だが、追加条件として 月間アクティブユーザー1億人、または月商2,000万ドルを超える事業者 には別途の取り扱いが課され、オンラインサービスとして提供する場合は帰属表示（attribution）が義務付けられる2。

AGPLv3はネットワーク越しにサービス提供した時点でソースコード開示義務が波及する「コピーレフト」ライセンスのため、SaaSやエンタープライズ製品に組み込む際の障壁になりやすい。今回の変更でその制約はほぼ撤廃され、大多数の開発者にとっては実質Apache 2.0相当で使えるようになった。閾値に達するような超大規模事業者だけが個別対応を検討すればよい設計だ。

CLIで動かす

インストールは uv 経由が推奨されている。

pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

実行はシンプルで、入力パスと出力先を指定するだけだ。

# GPU環境
mineru -p <input_path> -o <output_path>

# CPU専用環境
mineru -p <input_path> -o <output_path> -b pipeline

-b/--backend オプションには5種類の選択肢がある4。

backend 特徴
pipeline CPU専用環境向け。従来型のレイアウト検出＋OCR
vlm-engine VLMをローカルで実行
hybrid-engine pipelineとVLMを併用
vlm-http-client 外部VLMサーバーにHTTPで問い合わせ
hybrid-http-client hybrid構成を外部サーバー経由で実行

その他、-m/--method（auto/txt/ocr の抽出方式）、-l/--lang（言語指定）、--effort（medium/high、hybrid系のみ）、-f/--formula・-t/--table（数式・表解析の有効化）、-s/-e（ページ範囲指定）といったオプションが用意されている4。

実行後、出力ディレクトリには主に以下のファイルが生成される5。

ファイル 役割
{filename}.md メインのMarkdown変換結果
{filename}_content_list.json 読み順に整列した簡易構造データ
{filename}_middle.json ブロック階層を保持した詳細な中間データ
{filename}_layout.pdf レイアウト解析結果を可視化したPDF（デバッグ用）

MCP経由で使う

MinerUエコシステムには公式MCPサーバー mineru-open-mcp があり、Claude Desktop・Cursor・Windsurfから利用できる6（MCPプロトコル準拠クライアントであれば、原理上はClaude Code等の他クライアントからも接続できるが、公式ドキュメントが動作対象として明示しているのはこの3クライアントのみである）。uvx を使う場合の設定例は以下の通りだ。

{
  "mcpServers": {
    "mineru": {
      "command": "uvx",
      "args": ["mineru-open-mcp"],
      "env": {
        "MINERU_API_TOKEN": "your_key_here"
      }
    }
  }
}

MCP経由では parse_documents というツールが公開され、ローカルファイルとリモートURLの両方をMarkdown化できる6。

ここで公式ドキュメントを読み解いて気づいたのが、CLIとMCPで「無料」の意味が違う という点だ。CLIはローカルでモデルを動かすため、ページ数の上限なく処理できる（マシンスペックが許す限り）。一方MCP版には2つのモードがある36。

  • Flash mode: APIキー不要・無料。ただし 20ページ・10MBまで、出力はMarkdownのみ
  • Precision mode: MINERU_API_TOKEN が必須。200ページ・200MBまで 対応するが、設定した時点でFlash modeは無効化される

つまり「トークンを設定しなければ無料で使える」わけではなく、無料枠自体に20ページという上限が最初から組み込まれている。数百ページの社内マニュアルをMCP経由で気軽に流し込もうとすると、この上限に静かに引っかかることになる。CLIで動かしていた開発者がそのままMCPに移行すると体験のギャップに戸惑うはずだ。

まとめ

  • MinerUはPDF/Office文書をMarkdown/JSON化するOSSツールで、73.8kスター・109言語OCR対応と実績十分1
  • ライセンス変更（AGPLv3→Apache 2.0ベース）で商用導入の障壁は大幅に下がったが、超大規模事業者向けの追加条件は残る2
  • CLIはローカル実行でページ数無制限、MCP経由の無料Flash modeは20ページ・10MBが上限という非対称性がある。大量ドキュメントをAIエージェントに読ませる設計をするなら、CLIを直接叩くかPrecision mode用のAPIトークンを用意するかを事前に決めておくべきだ

参考リンク

  1. opendatalab/MinerU README（2026年7月時点、73.8kスター） ↩ ↩2 ↩3 ↩4

  2. MinerU LICENSE.md。ライセンス移行の経緯は MinerU: The Most Accurate Open-Source Document Parser Just Became Production-Ready（2026年6月）も参照 ↩ ↩2 ↩3 ↩4

  3. opendatalab/MinerU-Ecosystem mcpディレクトリ。Flash/Precisionモードの数値はMinerU公式APIドキュメントで確認 ↩ ↩2

  4. MinerU CLI Tools ↩ ↩2

  5. MinerU Output Files Reference ↩

  6. MinerU-Ecosystem mcp README。Flash/Precisionモードの数値はMinerU公式APIドキュメントで確認 ↩ ↩2 ↩3

2
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?