Mineru Pdf

Parse PDF documents with MinerU MCP to extract text, tables, and formulas. Supports multiple backends including MLX-accelerated inference on Apple Silicon.

Security Scan

The skill's code, instructions, and requirements are consistent with a PDF-parsing wrapper for MinerU MCP and do not request unrelated credentials or suspicious installs.

Purpose & Capability

Name/description match the included files and instructions: the SKILL.md and parse.py call MinerU components (via uvx/mcp-mineru or direct Python), and the declared required binary (uvx) is actually used in examples. There are no unrelated binaries or unexpected credential requests.

Instruction Scope

Instructions focus on parsing PDFs and saving outputs. parse.py reads a user-supplied PDF and writes parsed files to an output directory (persistent storage). Note: examples use absolute local paths (e.g., /Users/lwj04/...), and test.sh has a default PDF path under .openclaw/media/inbound — running the test.sh unmodified could act on that inbound file. This behavior is expected for a parsing tool but users should be aware it writes persistent files and that example paths are hard-coded.

Install Mechanism

No registry install spec is required by the platform; SKILL.md recommends installing via uvx / mcp-mineru (a package-managed installation). There are no downloads from unknown URLs or archive extractions in the skill files themselves.

Credentials

The skill declares no environment variables or credentials and only depends on the uvx binary and the MinerU Python package. That is proportionate for a PDF-parsing wrapper which either invokes uvx/mcp-mineru or imports mineru modules.

Persistence & Privilege

always is false and the skill does not request elevated system-wide privileges or modify other skills' configs. It writes output files to user-specified directories (intentional persistence), which is expected for this use case.

Assessment

This skill appears to do what it says: parse PDFs via MinerU MCP or the included Python wrapper. Before installing or running it: (1) ensure you trust the uvx/mcp-mineru package source and be aware that model downloads may occur on first use; (2) run parse.py with an explicit output_dir to avoid accidental writes to sensitive locations; (3) do not run test.sh without inspecting or replacing its default PDF path (it points to an inbound media file under ~/.openclaw); and (4) if you need stronger isolation, run the tool in a sandbox or VM since it will create persistent files and may download model artifacts.

MinerU PDF Parser

Parse PDF documents using MinerU MCP to extract structured content including text, tables, and formulas with MLX acceleration on Apple Silicon.

Installation

Option 1: Install MinerU MCP (for Claude Code)

claude mcp add --transport stdio --scope user mineru -- \
  uvx --from mcp-mineru python -m mcp_mineru.server

This installs and configures MinerU for all Claude projects. Models are downloaded on first use.

Option 2: Use Direct Tool (preserves files)

The skill includes a direct parsing tool that saves output to a persistent directory:

python /Users/lwj04/clawd/skills/mineru-pdf/parse.py <pdf_path> <output_dir> [options]

Advantages:

• ✅ Files are saved permanently (not auto-deleted)
• ✅ Full control over output location
• ✅ No MCP overhead
• ✅ Works with any Python environment that has MinerU

Quick Start

Method 1: Using the Direct Tool (Recommended)

# Parse entire PDF
python /Users/lwj04/clawd/skills/mineru-pdf/parse.py \
  "/path/to/document.pdf" \
  "/path/to/output"

# Parse specific pages
python /Users/lwj04/clawd/skills/mineru-pdf/parse.py \
  "/path/to/document.pdf" \
  "/path/to/output" \
  --start-page 0 --end-page 2

# Use Apple Silicon optimization
python /Users/lwj04/clawd/skills/mineru-pdf/parse.py \
  "/path/to/document.pdf" \
  "/path/to/output" \
  --backend vlm-mlx-engine

# Text only (faster)
python /Users/lwj04/clawd/skills/mineru-pdf/parse.py \
  "/path/to/document.pdf" \
  "/path/to/output" \
  --no-table --no-formula

Method 2: Using MinerU MCP (Temporary Files)

Parse a PDF document

uvx --from mcp-mineru python -c "
import asyncio
from mcp_mineru.server import call_tool

async def parse_pdf():
    result = await call_tool(
        name='parse_pdf',
        arguments={
            'file_path': '/path/to/document.pdf',
            'backend': 'pipeline',
            'formula_enable': True,
            'table_enable': True,
            'start_page': 0,
            'end_page': -1  # -1 for all pages
        }
    )
    if hasattr(result, 'content'):
        for item in result.content:
            if hasattr(item, 'text'):
                print(item.text)
                break

asyncio.run(parse_pdf())
"

Check system capabilities

uvx --from mcp-mineru python -c "
import asyncio
from mcp_mineru.server import call_tool

async def list_backends():
    result = await call_tool(
        name='list_backends',
        arguments={}
    )
    if hasattr(result, 'content'):
        for item in result.content:
            if hasattr(item, 'text'):
                print(item.text)
                break

asyncio.run(list_backends())
"

Parameters

parse_pdf

Required:

• file_path - Absolute path to the PDF file

Optional:

• backend - Processing backend (default: pipeline)
  • pipeline - Fast, general-purpose (recommended)
  • vlm-mlx-engine - Fastest on Apple Silicon (M1/M2/M3/M4)
  • vlm-transformers - Slowest but most accurate
• formula_enable - Enable formula recognition (default: true)
• table_enable - Enable table recognition (default: true)
• start_page - Starting page (0-indexed, default: 0)
• end_page - Ending page (default: -1 for all pages)

list_backends

No parameters required. Returns system information and backend recommendations.

Usage Examples

Extract tables from a specific page range

uvx --from mcp-mineru python -c "
import asyncio
from mcp_mineru.server import call_tool

async def parse_pdf():
    result = await call_tool(
        name='parse_pdf',
        arguments={
            'file_path': '/path/to/document.pdf',
            'backend': 'pipeline',
            'table_enable': True,
            'start_page': 5,
            'end_page': 10
        }
    )
    if hasattr(result, 'content'):
        for item in result.content:
            if hasattr(item, 'text'):
                print(item.text)
                break

asyncio.run(parse_pdf())
"

Parse with formula recognition only (faster)

uvx --from mcp-mineru python -c "
import asyncio
from mcp_mineru.server import call_tool

async def parse_pdf():
    result = await call_tool(
        name='parse_pdf',
        arguments={
            'file_path': '/path/to/document.pdf',
            'backend': 'vlm-mlx-engine',
            'formula_enable': True,
            'table_enable': False  # Disable for speed
        }
    )
    if hasattr(result, 'content'):
        for item in result.content:
            if hasattr(item, 'text'):
                print(item.text)
                break

asyncio.run(parse_pdf())
"

Parse single page (fastest for testing)

uvx --from mcp-mineru python -c "
import asyncio
from mcp_mineru.server import call_tool

async def parse_pdf():
    result = await call_tool(
        name='parse_pdf',
        arguments={
            'file_path': '/path/to/document.pdf',
            'backend': 'pipeline',
            'formula_enable': False,
            'table_enable': False,
            'start_page': 0,
            'end_page': 0
        }
    )
    if hasattr(result, 'content'):
        for item in result.content:
            if hasattr(item, 'text'):
                print(item.text)
                break

asyncio.run(parse_pdf())
"

Performance

On Apple Silicon M4 (16GB RAM):

• pipeline: ~32s/page, CPU-only, good quality
• vlm-mlx-engine: ~38s/page, Apple Silicon optimized, excellent quality
• vlm-transformers: ~148s/page, highest quality, slowest

Note: First run downloads models (can take 5-10 minutes). Models are cached in ~/.cache/uv/ for faster subsequent runs.

Output Format

Returns structured Markdown with:

• Document metadata (file, backend, pages, settings)
• Extracted text with preserved structure
• Tables formatted as Markdown tables
• Formulas converted to LaTeX

Supported Formats

• PDF documents (.pdf)
• JPEG images (.jpg, .jpeg)
• PNG images (.png)
• Other image formats (WebP, GIF, etc.)

Troubleshooting

Module not found error

If you get "No module named 'mcp_mineru'", make sure you installed it:

claude mcp add --transport stdio --scope user mineru -- \
  uvx --from mcp-mineru python -m mcp_mineru.server

Slow processing on first run

This is normal. MinerU downloads ML models on first use. Subsequent runs will be much faster.

Timeout errors

Increase timeout for large documents or use smaller page ranges for testing.

Notes

• Output is returned as Markdown text
• Tables are preserved in Markdown format
• Mathematical formulas are converted to LaTeX
• Works with scanned documents (OCR built-in)
• Optimized for Apple Silicon (M1/M2/M3/M4) with MLX backend

File Persistence

Why Files Get Deleted (MCP Method)

The MinerU MCP server uses Python's tempfile.TemporaryDirectory(), which automatically deletes files when the context exits. This is by design to prevent temporary files from accumulating.

How to Preserve Files

Method A: Use the Direct Tool (Recommended)

The skill provides parse.py which saves files to a persistent directory:

python /Users/lwj04/clawd/skills/mineru-pdf/parse.py \
  /path/to/input.pdf \
  /path/to/output_dir

Advantages:

• ✅ Files are never auto-deleted
• ✅ Full control over output location
• ✅ Can be used in batch processing
• ✅ No MCP connection needed

Generated Structure:

/path/to/output_dir/
├── input.pdf_name/
│   └── auto/          # or vlm/ depending on backend
│       ├── input.pdf_name.md
│       └── images/
│           └── *.jpg
└── input.pdf_name_parsed.md  # Copy at root for easy access

Method B: Redirect MCP Output

If using the MCP method, capture the output and save it:

# Capture to file
claude -p "Parse this PDF: /path/to/file.pdf" > /tmp/output.md

# Or use within a script that saves the result

Comparison

Feature	Direct Tool	MCP Method
Files persisted	✅ Yes	❌ No (auto-deleted)
Custom output dir	✅ Yes	❌ No (temp only)
Claude Code integration	⚠️ Manual	✅ Native
Speed	✅ Fast	⚠️ MCP overhead
Offline use	✅ Yes	⚠️ Needs Claude Code

Recommendation

• Use Direct Tool when you need to keep the files for later use
• Use MCP Method when working within Claude Code and only need the text content