mcpField
M
mineru-ocr

mineru-ocr

github.com/cat-xierluoドキュメント762115 回インストール今日更新
リポジトリ

mineru-ocr について

MinerUを使い、PDF、Office文書、画像、URLをMarkdownに変換する文書処理スキルです。トークン不要の軽量インターフェースと標準APIを切り替え、OCRや表、数式の認識にも対応します。

主な機能

  1. 01軽量インターフェースと標準APIの自動切替
  2. 02PDF、Office文書、画像の変換
  3. 03ローカルファイルとリモートURLの処理
  4. 04OCRによる文字認識
  5. 05表と数式の認識
  6. 06Markdownと関連結果の保存

活用シーン

  1. 01スキャン文書をMarkdownに変換
  2. 02文書からテキストや表を抽出
  3. 03リモート文書やウェブページURLを処理
  4. 04変換結果を後から確認できる形で保存

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/cat-xierluo/legal-skills --skill mineru-ocr

インストール後、Claude Code で/mineru-ocrを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

CHANGELOG.md
LICENSE.txt
scripts/
convert.js

詳細

MinerU PDF から Markdown への変換

事前設定

デフォルトの Auto モード：Token が設定されていない場合は、公式のログイン不要な軽量インターフェースを自動的に使用します。Token が設定されると、標準 API に自動的に切り替わります。

設定不要ですぐに使う
  • ログインや .env の作成は不要です
  • ローカルの小さなファイルやリモート文書 URL をすばやく変換する場合に適しています
  • 公式の軽量インターフェースの制限が適用されます：IP ごとの利用頻度制限、単一ファイル 10 MB、最大 20 ページ
標準 API にアップグレード（任意）

以下のいずれかに該当する場合は、Token の設定をおすすめします：

  • ファイルが 10 MB を超える
  • ページ数が 20 ページを超える
  • 軽量インターフェースで IP ごとの利用頻度制限が発生する
  • ウェブページ URL を抽出する必要がある
  • より安定して標準 API の利用枠を使いたい
API Token の申請
  1. https://mineru.net/apiManage/token にアクセスします
  2. アカウントを登録／ログインします
  3. API Token を作成してコピーします（形式：eyJ0eXAiOiJKV1QiLCJhbGc...）
Token の設定

方法一：AI に設定を依頼する

「MinerU の設定を手伝ってください。Token は xxx です」

方法二：手動で設定する

cd .claude/skills/mineru-ocr/config
cp .env.example .env
nano .env  # 填入 MINERU_API_TOKEN

方法三：公式 CLI に保存済みの Token を再利用する

公式の mineru-open-api auth をすでに実行している場合、この skill では ~/.mineru/config.yaml に保存されている Token の読み込みも試みます。

現在の読み込み優先順位は次のとおりです：

  1. この skill の .claude/skills/mineru-ocr/config/.env にある MINERU_API_TOKEN
  2. 環境変数 MINERU_API_TOKEN
  3. 環境変数 MINERU_TOKEN
  4. 公式 CLI の設定 ~/.mineru/config.yaml
Token の更新

現在のルールでは、Token の有効期間は 3 か月（約 90 日） です。有効期限が切れると変換に失敗します（エラー 401 または Unauthorized）。

更新するには、AI に「MinerU Token の有効期限が切れました。新しい Token は xxx です」と伝えてください。

機能の説明

MinerU を使用して文書を Markdown 形式に変換します。次の機能に対応しています：

  • Auto モード：Token がない場合はログイン不要の軽量インターフェースを使用し、Token がある場合は標準 API を使用します
  • PDF、DOC、DOCX、PPT、PPTX、PNG、JPG、JPEG
  • ローカルファイル、リモート文書 URL、ウェブページ URL
  • OCR による文字認識
  • 表の認識と保持
  • 数式の認識
  • 結果のアーカイブ：Markdown、API レスポンス、関連する画像リソースを保持し、後から確認できるようにします

対応範囲

シナリオログイン不要の軽量インターフェース標準 Token API
ローカルの PDF／画像／Docx／Pptx対応対応
リモート文書 URL（PDF、画像、Doc／Docx、PPT／Pptx）対応対応
ウェブページ URL／HTML非対応対応
単一ファイルのサイズ10 MB 以内200 MB 以内
ページ数の制限20 ページ以内600 ページ以内
表の認識非対応。公式の案内では標準モードへのアップグレードが必要です対応
数式の認識非対応。公式の案内では標準モードへのアップグレードが必要です対応
出力MarkdownZip 結果パッケージ + Markdown／JSON／追加形式
軽量モードが適しているケース
  • 初回の使用や、すばやい試用
  • ローカルの小さなファイル
  • リモートの PDF／Doc／Ppt リンク
  • 表や数式の認識が不要な場合
標準 API が適しているケース
  • 大きなファイルや長い文書
  • 表、数式、複雑なレイアウトをより重視するシナリオ
  • ウェブページ URL の抽出
  • より完全な結果パッケージを取得し、中間結果も多く保持したい場合

使用方法

/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js "/path/to/file.pdf"
/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js "https://cdn-mineru.openxlab.org.cn/demo/example.pdf"
/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js "https://example.com/article"
/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js checktoken

設定オプション

.claude/skills/mineru-ocr/config/.env を編集します：

オプションデフォルト値説明
MINERU_API_TOKEN空任意。設定すると標準 Token API を強制的に使用します
MINERU_ENABLE_OCRtrueOCR を有効にします
MINERU_ENABLE_TABLEtrue表の認識を有効にします。主に標準 Token API で有効です
MINERU_ENABLE_FORMULAfalse数式の認識を有効にします。主に標準 Token API で有効です
MINERU_LANGUAGE_CODEch言語コード
MINERU_API_BASEhttps://mineru.net/api/v4標準 API のアドレス
MINERU_MODEL_VERSIONpipeline標準 Token API のモデル。法律文書ではデフォルトの pipeline を推奨します。複雑なレイアウトでは vlm に変更できます
MINERU_PAGE_RANGES空標準 Token API のページ範囲。例：1-20、2,4-6
MINERU_POLL_MAX20最大ポーリング回数
MINERU_POLL_SLEEP10ポーリング間隔（秒）
MINERU_LOG_LEVELmediumログレベル

出力

  • ローカルファイル：Markdown は元ファイルと同じディレクトリに保存されます
  • リモート文書 URL／ウェブページ URL：Markdown はコマンドの実行時における現在のディレクトリに保存されます
  • アーカイブ：.claude/skills/mineru-ocr/archive/日付_時刻_ファイル名/
  • アーカイブの内容：変換された Markdown、API レスポンス、入力ファイル、ダウンロード可能な画像リソースの一覧

法律文書に関する推奨事項

  • デフォルトの MINERU_MODEL_VERSION=pipeline を維持します
  • 訴状、証拠目録、裁判所からの通知、召喚状などの正式な文書では、安定性とハルシネーションのリスク低減を優先し、デフォルトで vlm に変更することはおすすめしません
  • スキャン品質が低い場合、レイアウトが非常に複雑な場合、または表が多い場合に限り、vlm への切り替えを検討してください
  • 訴訟記録の最初の数ページだけを確認したい場合は、MINERU_PAGE_RANGES=1-20 を設定できます

Token の自己診断

現在の Token が有効か確認したい場合は、次を実行します：

/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js checktoken
  • Token が設定されていない場合：現在は軽量モードであることが通知されます
  • Token が有効な場合：標準 API が利用可能であることが通知されます
  • Token が無効な場合：再申請と更新が必要であることが明示されます

クラウドモード／カスタムアドレス

現在、この skill は公式クラウド APIのみを対象としています。

独自のクラウド転送ゲートウェイを使用する必要があり、そのゲートウェイが公式 v4 API と互換性がある場合は、.env で次の値を変更できます：

MINERU_API_BASE=https://your-gateway.example.com/api/v4

現在のスクリプトは、デフォルトで公式クラウド v4 API のワークフローに対応しています。

公式の mineru-api／mineru-router FastAPI サービスをデプロイしている場合、主に /tasks、/file_parse などのインターフェースを公開しており、この skill の現在の対応範囲には含まれません。このような場合は、次の方法をおすすめします：

  • 公式 CLI／SDK を使用して、自前のサービスに直接接続します
  • この skill は引き続きクラウドモードのみを管理し、別のプロトコルが混在しないようにします

公式 Crawl について

公式 skill のウェブページ抽出は、主に CLI の mineru-open-api crawl <url> で実行されます。これはToken モードの機能であり、軽量インターフェースの機能ではありません。

ここでいう CLI は公式が提供するコマンドラインのラッパー層です。CLI は内部で引き続き MinerU のクラウド API を呼び出します。ローカルで動作するオフラインパーサーではありません。

現在お使いのこの skill もウェブページ URL に対応していますが、Token が設定されている場合に限り有効になります。Token が設定されていない場合、ウェブページ URL を使用するには標準 API に切り替えるよう案内されます。

故障排除

问题解决方案
轻量接口限频稍后重试，或配置 Token 切换到标准 API
文件过大 / 页数过多配置 Token，改走标准 API
网页 URL 无法轻量解析轻量接口不支持 HTML，请配置 Token
401/UnauthorizedToken 已过期，重新申请并更新
转换超时增加 MINERU_POLL_MAX 或检查文件大小
配额不足检查 MinerU 账户额度

コメント

Markdown 対応