MinerU MCP

English · Español

MinerU MCP — Model Context Protocol (MCP) 経由でAIエージェント向けにPDFを抽出・解析

あらゆるPDFドキュメントを、AIエージェント向けの構造化Markdown、表、LaTeXコードに変換します。 MinerU（PDF-Extract-Kit / MinerU2.5-VLM）の抽出機能を、Claude Code、Cursor、Windsurf、Hermes Gateway、およびModel Context Protocolに対応するあらゆるクライアントに公開するオープンソースのMCPサーバーです。FastMCP HTTP/SSEに対応し、ローカルパスまたはBase64を利用できます。クライアント側の依存関係は不要で、処理はすべてお使いのハードウェア上で行われます。

タグ: mcp-server · mineru · pdf-parser · ocr · latex · ai-agents · fastmcp · claude-code · cursor · hermes-gateway · local-first · self-hosted

_{エージェントがMCP経由でPDFを送り、LaTeXの数式と表を含むMarkdownを受け取ります — MinerUはお使いのサーバーで動作し、クライアントへのPyTorchのインストールは不要です。実際のmineru-apiを使い、scripts/demo_parse.pyで録画しました。}

---

💡 このプロジェクトが生まれた理由

PDFファイルから構造化テキスト、複雑な表、数式を抽出するには、通常、各クライアントマシンにPyTorch、OCR、ビジョンモデルを含む重いPython環境が必要です。MinerU MCPは、疎結合のHTTP/SSEミドルウェアアダプターとして動作することで、この問題を解決します。

• 🚀 ローカルへのインストール不要：あらゆるMCPクライアントが、ポート8202でHTTP/SSE経由のドキュメント処理を行えます。ローカルのfile_pathを渡すか、PDFをfile_base64にエンコードして送信します。
• 📊 構造化MarkdownとLaTeX：見出し、リスト、複雑な表、数式を、RAGですぐに使える標準的なLaTeXコードに変換します。
• 🧠 GPUを奪い合わずに共有：pipeline（デフォルト）が必要とするVRAMは約1.5 GB、hybrid-engineとvlm-engineは約4 GBで、より高い精度が得られます。ホストにGPU Brokerがある場合、各解析処理は開始前にVRAMを要求し、終了後に返却するため、同じGPU上でローカルLLMと共存できます。

---

⚡ クイックスタート

mineru-mcpはMCPレイヤーのみを提供します。実行中のmineru-api（mineru==3.4.4）が必要です。ホストへのセットアップ方法はdocs/SERVER_SETUP.mdを参照してください。

起動方法は2種類あります。いずれかを選んでください。

モード	用途	起動方法
HTTP	mineru-apiが動作するマシンでサーバーを起動し、ネットワーク上のすべてのクライアントで共有する場合（主な用途）	自分で（またはサービスとして）起動すると、http://<server>:8202/mcpでリクエストを待ち受けます。
stdio	クライアントがmineru-apiと同じマシンで動作する場合	クライアントがプロセスを自動的に起動します（uvxまたはDocker）。ポートは開きません。

要件：uv ≥ 0.13.4（またはpip ≥ 26.2.2）。それ以前のバージョンは、侵害されたCA emSign（GHSA-6q48-6c7w-9gw2）を引き続き信頼します。uv pip install -e .は自動で確認します（pyproject.tomlの[tool.uv] required-version）。一方、uvx --from git+…はプロジェクト外で実行されるため確認しません。uv --versionで確認してください。

オプション A — HTTP（共有サーバー）

git clone https://github.com/GermaniU/mineru-mcp.git
cd mineru-mcp
uv venv && source .venv/bin/activate
uv pip install -e .
MINERU_URL=http://127.0.0.1:8000 mineru-mcp

MCP エンドポイント：http://<server>:8202/mcp。クライアントの設定に貼り付けてください（docs/CLIENTS.md — Claude Code、Cursor、Continue、OpenCode、Hermes Gateway を参照）。

オプション B — Docker で stdio

ghcr.io/germaniu/mineru-mcp イメージは stdio 経由で MCP を通信し、ホスト上で実行されている mineru-api を呼び出します。MCP クライアントで設定してください。

{
  "mcpServers": {
    "mineru": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--add-host", "host.docker.internal:host-gateway",
        "-e", "MINERU_URL=http://host.docker.internal:8000",
        "ghcr.io/germaniu/mineru-mcp:latest", "--stdio"
      ]
    }
  }
}

コンテナ内では、file_path はコンテナのファイルシステムを参照します。ドキュメントは file_base64 + file_name で送信するか、-v でディレクトリをマウントしてください。コンテナ内には systemd がないため、オンデマンド起動も GPU Broker も利用できません。mineru-api はあらかじめ起動しておく必要があります。

Docker を使わない場合：uv ≥ 0.13.4 で uvx --from git+https://github.com/GermaniU/mineru-mcp mineru-mcp --stdio を実行してください（設定は docs/CLIENTS.md を参照）。

🔍 診断

mineru_health は、mineru-api が応答するかどうか、そのバージョン、キュー内のタスクを示し、バックエンドがスリープ中（非アクティブのため停止）か故障中かを区別します。MCP クライアントなしでも、curl によるスモークテストで呼び出せます。

---

⚙️ 設定（環境変数）

.env ファイルを作成するか、次の変数をエクスポートします。

変数	デフォルト値	説明
MINERU_URL	http://127.0.0.1:8000	mineru-api の URL です。loopback と host.docker.internal のみ受け付けます。それ以外のホストの場合、ツールはドキュメントの送信を拒否します。
MINERU_BACKEND	pipeline	呼び出し側で空の場合に使用するバックエンド（pipeline、hybrid-engine、vlm-engine）。
MINERU_PARSE_METHOD	auto	呼び出し側で空の場合に使用する抽出方法（auto、txt、ocr）。
MINERU_LANG	es	呼び出し側で空の場合に使用する OCR 言語。
MINERU_SYSTEMCTL_SCOPE	user	起動と状態確認の対象となる mineru-api の unit の場所：user（systemctl --user）または system（/etc/systemd/system）。それ以外の値ではサーバーを起動できません。
MCP_HOST	0.0.0.0	HTTP モードのホストバインディング。
MCP_PORT	8202	HTTP モードのポート。
MCP_AUTH_TOKEN	(空 = 認証なし)	設定すると、HTTP モードでは各リクエストに Authorization: Bearer <token> が必要です。
MCP_TRANSPORT	(空 = HTTP)	stdio は --stdio を渡すのと同じです。

各設定で保護される内容と保護されない内容については、SECURITY.md を参照してください。

---

🛠️ 公開ツール（ツールリファレンス）

ツール	説明
parse_document	PDF、DOCX、PPTX、XLSX、画像を Markdown に同期的に解析します（30～120 秒）。入力：file_path（サーバー上のパス）または file_base64 + file_name。オプション：backend、effort、image_analysis、parse_method、lang、formula_enable、table_enable、start_page、end_page。
submit_parse_task	parse_document と同じですが、非同期で処理し、task_id を返します。約50ページを超えるドキュメントに使用します。
get_task_status	タスクの状態（pending / processing / completed / failed）。
get_task_result	完了したタスクの Markdown。
mineru_health	mineru-api の稼働状況、バージョン、キュー内のタスク。

start_page と end_page は0から数えます。デモでは start_page: 4, end_page: 5 を指定し、論文の5ページ目と6ページ目を受け取ります。hybrid-engine + effort=high + image_analysis=true を指定すると、図を Mermaid ダイアグラムに変換します。

---

🎯 現在の範囲

MinerU MCP は意図的に機能を絞っています。行うことは1つだけです。MCP クライアントから mineru-api にドキュメントを渡し、Markdown を返します。解析は MinerU が行います。

できること

• ✅ PDF、DOCX、PPTX、XLSX、PNG、JPG を、見出し、表（HTML）、数式（LaTeX）を含む Markdown に変換します。
• ✅ 別のマシンから、ドキュメントをサーバーのパス（file_path）またはコンテンツ（file_base64 + file_name）として受け取ります。
• ✅ 短いドキュメントは同期で解析し、長いドキュメントは task_id を使って非同期で解析します。ページ範囲も指定できます。
• ✅ mineru-api が停止していて systemd がある場合は、起動し（systemctl --user start、または MINERU_SYSTEMCTL_SCOPE=system の場合は --user なし）、応答するまで待ってから解析します。
• ✅ ホストに GPU Broker がある場合は、VRAM を要求し、使用後に返却します。

できないこと（現時点）

• ❌ mineru-api やモデルは含まれていません。ホストに別途インストールし、サービスを構成してください：docs/SERVER_SETUP.md。
• ❌ ドキュメントをネットワークの外に送信しません。MINERU_URL がループバックアドレスでない場合、送信を拒否します。MinerU のクラウド API は使用しません。
• ❌ 抽出した画像は返しません。Markdown のみを返します。
• ❌ 長い抽出処理では Markdown を部分的にストリーミングしません。submit_parse_task を使って状態を確認します。
• ❌ ドキュメントや結果は保存しません。base64 用の一時ファイルは処理完了時に削除されます。
• ❌ Docker ではオンデマンド起動も GPU Broker も利用できません。mineru-api を起動しておく必要があります。

「できないこと」の一覧にある機能が必要な場合は、実際のユースケースを添えて issue を作成してください。

---

🧭 ほかのドキュメント用 MCP サーバーとの違いは？

3 つの種類があり、それぞれ異なる問題を解決します。

	MinerU MCP（このサーバー）	MinerU 公式 MCP（クラウド）	汎用コンバーター（Docling、MarkItDown）
解析場所	お使いのハードウェア上の mineru-api	MinerU のクラウド API	MCP が実行されるマシン
ドキュメントがネットワークの外に出るか	いいえ（外部 URL をブロック）	はい	いいえ
アカウント／トークン	不要	MinerU API のトークン	不要
クライアント側の依存関係	なし（HTTP）、または Docker のみ（stdio）	Python（uvx mineru-open-mcp）	変換エンジン一式
ローカル LLM と GPU を共有	はい（GPU Broker）	該当なし	いいえ
エンジン	MinerU（pipeline／vlm／hybrid）	MinerU	各製品独自のエンジン

一言で言うと：

• GPU もサーバーもなく、ドキュメントをアップロードしても問題ない場合 → MinerU 公式のクラウド MCP。
• クライアントと同じマシンで動くコンバーターが必要な場合 → Docling または MarkItDown。
• すでに MinerU を自分のサーバーで運用している（または運用したい）場合で、ドキュメントをネットワークの外に出さず、LAN 上のすべてのクライアントで共有したい場合 → こちら。

---

🔌 クライアントを接続する

docs/CLIENTS.md に、そのままコピーできる設定例（HTTP と stdio）があります。

• 🟦 Claude Code — claude mcp add -s user -t http mineru http://<server>:8202/mcp（ツールは新しいセッションで表示されます）。
• 🟧 Cursor — Settings → MCP Servers → Add new MCP Server。
• 🟩 Continue（VS Code / JetBrains）— ~/.continue/config.json。
• 🟪 OpenCode — ~/.config/opencode/config.json。
• 🟨 Hermes Gateway — ~/.hermes/config.yaml の mcp_servers。
• 🟫 Claude Desktop — mineru-api が稼働するマシン上で、uvx または Docker を使う stdio。

すぐに使えるスニペットは examples/ にあります。

---

🧪 curl によるスモークテスト

HTTP モードは ステートレス です。initialize や mcp-session-id は不要で、リクエスト 1 回で実行できます。

curl -sS -X POST http://localhost:8202/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mineru_health","arguments":{}}}'

MCP_AUTH_TOKEN を設定している場合は、-H "Authorization: Bearer <token>" を追加してください。

GIF のデモのように、ヘルスチェックと arXiv 論文の 2 ページを実際に解析する一連のテストを行うには：

MCP_DEMO_URL=http://localhost:8202/mcp python scripts/demo_parse.py

---

🧱 アーキテクチャ

⚠️ システムの制限： mineru-mcp はトランスポートと MCP インターフェースの層のみです。処理エンジン mineru-api や、HuggingFace モデルのキャッシュダウンロードは含まれていません。

 +-------------------------------------------------------+
 |                 Clientes MCP (LAN)                    |
 | (Claude Code CLI / Cursor / Windsurf / Hermes Gateway)|
 +-------------------------------------------------------+
                             |
                             | HTTP / SSE (Puerto 8202)
                             v
 +-------------------------------------------------------+
 |                   mineru-mcp Server                   |
 |        (FastMCP + File Path / Base64 Decoder)         |
 +-------------------------------------------------------+
                             |
                             | Loopback HTTP (Puerto 8000)
                             v
 +-------------------------------------------------------+
 |                  MinerU Backend Host                  |
 |  (mineru-api + PDF-Extract-Kit + HuggingFace Cache)   |
 +-------------------------------------------------------+

各ツールは src/mineru_mcp/tools/ にあり、server.py はそれらを FastMCP に登録してトランスポートを起動するだけです。技術的な詳細は docs/ARCHITECTURE.md をご覧ください。

---

🤝 貢献

PR、issue、forkを歓迎します（MIT）。

ルール（概要）：

1. 小さく、直接的な変更にしてください。 問題を解決するために必要な、最も狭い範囲のコードだけを変更します。
2. 推測に基づく抽象化や、不要な依存関係の追加は避けてください。
3. ツールの名前とパラメーターは変更しないでください。 クライアントがそれらに依存しています。
4. 識別子は英語、コメントとコミットメッセージはスペイン語にしてください。Conventional Commits（feat:、fix:、docs:、refactor:、test:、chore:）を使用します。

詳細は CONTRIBUTING.md をご覧ください。

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest          # unit tests, sin mineru-api
ruff check .

---

🩹 トラブルシューティング

mineru_health が MinerU no disponible (el backend está inactivo) と応答する

• mineru-api が停止しています（たとえば、アイドル状態のときにVRAMを解放するウォッチドッグによる停止など）。これはエラーではありません。parse_document または submit_parse_task が起動します。

BLOQUEADO por seguridad: MINERU_URL apunta a …

• MINERU_URL がループバックアドレスでも host.docker.internal でもありません。これは意図的な動作です。ドキュメントがマシンの外に送信されることはありません。詳しくは SECURITY.md をご覧ください。

MinerU no respondió tras 90s de arrancarlo または、バックエンドが起動しているのに mineru_health が inactivo と表示する

• スコープがユニットと一致していません。MINERU_SYSTEMCTL_SCOPE=user は ~/.config/systemd/user/mineru-api.service を検索し、system は /etc/systemd/system/mineru-api.service を検索します。user の場合、MCP は同じユーザーの systemd セッションで実行する必要があります（たとえば、ユーザーユニットとして実行します）。詳しくは docs/SERVER_SETUP.md をご覧ください。

MinerU no responde en … y aquí no hay systemd para arrancarlo

• DockerまたはmacOSで実行しています。mineru-api を起動する方法がありません。手動で起動してから、もう一度試してください。

エンドポイントへの curl で 406 Not Acceptable が返される

• Accept: application/json, text/event-stream ヘッダーがありません。

401 {"error":"unauthorized"}

• サーバーに MCP_AUTH_TOKEN が設定されています。Authorization: Bearer <token> を送信してください。

Error: timeout. El documento puede ser muy grande

• submit_parse_task を使用して get_task_status で状態を確認するか、start_page / end_page で範囲を指定して解析してください。

---

📚 ドキュメント

• docs/SERVER_SETUP.md — mineru-api、モデル、ホスト上のサービスのインストール。
• docs/CLIENTS.md — Claude Code、Cursor、Continue、OpenCode、Hermes Gateway、Claude Desktop の設定。
• docs/ARCHITECTURE.md — コンポーネント、リクエストの処理フロー、GPU Arbiter。
• SECURITY.md — 脅威モデルと脆弱性の報告方法。
• CONTRIBUTING.md — 開発環境、スタイルルール、ワークフロー。
• CHANGELOG.md — 変更履歴。

---

📄 ライセンス

MIT — 使用、フォーク、改良は自由です。

---

@GermaniU によって作成されました。 役に立った場合は、⭐を付けていただけると、より多くの人に見つけてもらいやすくなります。問題が起きた場合は、issueを作成してください。一緒に解決します。