MinerU Dify Plugin

GitHub

MinerU is a tool that converts PDFs into machine-readable formats (e.g., markdown, JSON), allowing for easy extraction into any format.

MinerU is a document parser that can parse complex document data for any downstream LLM use case (RAG, agents)

GitHub - opendatalab/MinerU: A high-quality tool for convert PDF to Markdown and JSON.

Key Features

• Remove headers, footers, footnotes, page numbers, etc., to ensure semantic coherence.
• Output text in human-readable order, suitable for single-column, multi-column, and complex layouts.
• Preserve the structure of the original document, including headings, paragraphs, lists, etc.
• Extract images, image descriptions, tables, table titles, and footnotes.
• Automatically recognize and convert formulas in the document to LaTeX format.
• Automatically recognize and convert tables in the document to HTML format.
• Automatically detect scanned PDFs and garbled PDFs and enable OCR functionality.
• OCR supports detection and recognition of 84 languages.
• Supports multiple output formats, such as multimodal and NLP Markdown, JSON sorted by reading order, and rich intermediate formats.
• Supports various visualization results, including layout visualization and span visualization, for efficient confirmation of output quality.
• Supports running in a pure CPU environment, and also supports GPU(CUDA)/NPU(CANN)/MPS acceleration
• Compatible with Windows, Linux, and Mac platforms.

What's New in 0.6.1

• Accept self-hosted V1 API addresses ending in , including reverse-proxy prefixes such as . The plugin adds the API version exactly once, avoiding and an incorrect fallback to .
• Report health-check failures and unexpected responses instead of treating them as MinerU 1.x–3.x. Legacy fallback is limited to a missing or unsupported V1 health endpoint (HTTP 404/405).

MinerU 4.x support was introduced in 0.6.0. If an older plugin calls and receives 404 after upgrading MinerU, update the plugin, select Local Deployment, and point Base URL at the document parsing service (). The WebUI and OpenAI-compatible VLM service are different endpoints.

The V1 integration follows the official HTTP API guide and 4.0 migration guide: upload → parse job → poll → download output files. Existing workflows keep the same tool parameters; maps to V1 , to per-file , and selects parsing quality.

What's New in 0.6.0

• Self-hosted MinerU 4.x support. MinerU 4.x replaced with the V1 API (uploads → parse jobs → output files). The plugin detects the server version automatically, so the same configuration works with MinerU 1.x, 2.x, 3.x and 4.x, and you can upgrade the MinerU server without changing the plugin.
• New tool: Parse URL – let MinerU download and parse a document from an http(s) URL (official API and MinerU 4.x).
• New tool: Get Parse Result – fetch the status or result of a job by / . Together with the new and options of Parse File, long documents no longer have to finish within one tool call.
• Page ranges – parse only some pages of a PDF (e.g. ).
• Gateway header – optional fixed header (e.g. ) for self-hosted MinerU behind a gateway or reverse proxy, sent in addition to the API token.
• More file types – xls/xlsx, more image formats, and html (official API model or MinerU 4.x).
• Fixes for self-hosted MinerU 2.x/3.x – the formula/table recognition switches and the document language are now actually sent to the server.
• New output variables , , and ; clearer error messages (expired token, quota, gateway or API-key rejections).
• Removed the unused "Replace Markdown Image Path" tool files; image links in the Markdown are replaced automatically.

DEMO DSL

You can download the YAML file and import it into Dify. This demo includes a basic capability demonstration of the plugin.

demo_dsl.yml

Tools

Configuration

Go to "Tools" → "Plugin Market", add the "MinerU" plugin and fill in its credentials. You can save several credentials (for example one for the official API and one for an internal server) and pick one per node.

Saving the credentials checks them with a read-only request.

Network notes for self-hosted servers

• Dify must be able to reach the Base URL. Do not use or unless MinerU runs on the same host as the Dify plugin daemon.
• Requests come from the Dify plugin daemon. If the gateway uses an IP allowlist, allow the plugin daemon's address.
• MinerU 2.x/3.x has no authentication of its own; keep it on an internal network or behind a gateway. For MinerU 4.x, start the server with when it listens on a non-loopback address.

Starting a self-hosted server

• MinerU 4.x: (see the MinerU HTTP API guide). needs no models; runs on CPU; / need a VLM.
• MinerU 2.x/3.x: .

Parse File / Parse URL parameters

Output Variables

Long documents

1. Run Parse File (or Parse URL) with off, or let it reach .
2. Pass its and outputs to Get Parse Result, e.g. inside a Loop node, until is .

Use the same credential for both tools – job ids only exist on the server that created them. A self-hosted MinerU 4.x server keeps jobs in memory, so job ids do not survive a server restart.

Important: Dify Environment Configuration ()

To ensure the MinerU plugin can properly handle file uploads, you need to configure the setting in Dify:

1. Find your Dify deployment directory and edit the file.

2. Modify the configuration based on your deployment method:

   • Docker Compose deployment: Set to
   • Other deployment methods: Set to (e.g., , where the IP is usually the machine running Dify)

3. Confirm that the Dify API service's port is exposed externally (check port mapping in the file).

4. After saving the file, restart the Dify service for the configuration to take effect:

Tips:

• If you use your local IP for the , your IP address may change when your network environment changes (e.g., connecting to a different WiFi). When this happens, you'll need to:

  • Get your new local IP address
  • Update the MinerU plugin's Base URL configuration in Dify
  • If necessary (if Dify's is configured with an IP address rather than ), update Dify's file and restart the Dify service

• When using the Dify MinerU plugin, especially when processing file uploads, if you don't configure this step, you may encounter errors like . This usually occurs because Dify's service cannot correctly access its own file service.

FAQs

1. What should I do if I encounter the following error during execution?

---

Please follow the instructions above to configure the settings accordingly, and this issue will be resolved.

https://github.com/langgenius/dify/issues/16327

2. "This MinerU server cannot export the requested extra formats" – self-hosted MinerU 4.x only returns Markdown, JSON and images. Leave Extra export formats empty.

3. "The MinerU API token has expired" – generate a new token at https://mineru.net/apiManage/token and update the plugin credentials.

Credits

This plugin is powered by MinerU