MinerU-Ecosystem
The official ecosystem toolkit for MinerU Open API
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/opendatalab--mineru-ecosystem)HTML
<a href="/listings/opendatalab--mineru-ecosystem"><img src="/api/listings/opendatalab--mineru-ecosystem/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
π» CLI (`cli/`)
A fast command-line tool for parsing documents directly from your terminal.
Installation
# Linux / macOS curl -fsSL https://cdn-mineru.openxlab.org.cn/open-api-cli/install.sh | sh
# Windows (PowerShell) irm https://cdn-mineru.openxlab.org.cn/open-api-cli/install.ps1 | iex
**Flash Extract (no login)**
mineru-open-api flash-extract report.pdf
**Precision Extract (login required)**
# First-time setup mineru-open-api auth # Extract to stdout mineru-open-api extract paper.pdf # Save all resources (images/tables) to directory mineru-open-api extract report.pdf -o ./output/ # Export to multiple formats mineru-open-api extract report.pdf -f docx,latex,html -o ./results/
**Web Crawl**
mineru-open-api crawl https://www.example.com
**Batch Processing**
# All PDFs in current directory mineru-open-api extract *.pdf -o ./results/ # From a file list mineru-open-api extract --list filelist.txt -o ./results/
---
π Python SDK
Installation
pip install mineru-open-sdk
**Flash Extract (no token)**
from mineru import MinerU
client = MinerU()
result = client.flash_extract("https://cdn-mineru.openxlab.org.cn/demo/example.pdf")
print(result.markdown)**Precision Extract (token required)**
from mineru import MinerU
client = MinerU("your-api-token")
result = client.extract("https://cdn-mineru.openxlab.org.cn/demo/example.pdf")
print(result.markdown)
print(result.images) # extracted image list---
πΉ Go SDK
Installation
go get github.com/opendatalab/MinerU-Ecosystem/sdk/go@latest
**Flash Extract**
package main
import (
"context"
"fmt"
mineru "github.com/opendatalab/MinerU-Ecosystem/sdk/go"
)
func main() {
client := mineru.NewFlash()
result, err := client.FlashExtract(
context.Background(),
"https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
)
if err != nil {
panic(err)
}
fmt.Println(result.Markdown)
}**Precision Extract**
client, err := mineru.New("your-api-token")
if err != nil {
panic(err)
}
result, err := client.Extract(
context.Background(),
"https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
)
if err != nil {
panic(err)
}
fmt.Println(result.Markdown)**Precision Extract with options**
result, err := client.Extract(ctx, "./paper.pdf",
mineru.WithModel("vlm"),
mineru.WithLanguage("en"),
mineru.WithPages("1-20"),
mineru.WithExtraFormats("docx"),
mineru.WithPollTimeout(10*time.Minute),
)
if err != nil {
panic(err)
}
if err := result.SaveAll("./output"); err != nil {
panic(err)
}**Batch Processing**
ch, err := client.ExtractBatch(ctx, []string{"a.pdf", "b.pdf"})
if err != nil {
panic(err)
}
for result := range ch {
fmt.Printf("%s: %s\n", result.Filename, result.State)
}**Web Crawling**
result, err := client.Crawl(ctx, "https://www.example.com")
if err != nil {
panic(err)
}
fmt.Println(result.Markdown)---
π¦ TypeScript / JavaScript SDK
Installation
npm install mineru-open-sdk
**Flash Extract**
import { MinerU } from "mineru-open-sdk";
const client = new MinerU();
const result = await client.flashExtract(
"https://cdn-mineru.openxlab.org.cn/demo/example.pdf"
);
console.log(result.markdown);**Precision Extract**
import { MinerU } from "mineru-open-sdk";
const client = new MinerU("your-api-token");
const result = await client.extract(
"https://cdn-mineru.openxlab.org.cn/demo/example.pdf"
);
console.log(result.markdown);
console.log(result.images);**Precision Extract with options**
import { MinerU, saveAll } from "mineru-open-sdk";
const client = new MinerU("your-api-token");
const result = await client.extract("./paper.pdf", {
model: "vlm", // "vlm" | "pipeline" | "html"What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md Β· README Β· 570 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <div align="center">
- # MinerU-Ecosystem
- **The official ecosystem toolkit for [MinerU](https://github.com/opendatalab/MinerU) Open API**
- Empowering developers and AI agents with seamless document parsing capabilities β PDF Β· Word Β· PPT Β· Images Β· Web pages β Markdown / JSON Β· VLM+OCR dual engine Β· 109 languages Β· MCP Server Β· LangChain / RAGFlow / Dify / FastGPT native integration.
- [](LICENSE)
- [](https://github.com/opendatalab/MinerU)
- [](https://mineru.net)
- [δΈζζζ‘£](README.zh-CN.md)
- </div>
- ---
- ## π Overview
- **MinerU-Ecosystem** provides a full suite of tools, SDKs, and integrations built on top of the [MinerU Open API](https://mineru.net/apiManage/docs). Whether you're building production pipelines, integrating with LangChain for RAG, or enabling AI agents to parse documents on the fly β this repository has you covered.
- [MinerU](https://github.com/opendatalab/MinerU) is an open-source, high-accuracy document parsing engine that converts unstructured documents (PDFs, images, Office files, etc.) into machine-readable Markdown and JSON, purpose-built for LLM pre-training, RAG, and agentic workflows.
- **Core capabilities:**
- - Formulas β LaTeX Β· Tables β HTML, accurate complex layout reconstruction
- - Supports scanned docs, handwriting, multi-column layouts, cross-page table merging
- - Output follows human reading order with automatic header/footer removal
- - VLM + OCR dual engine, 109-language OCR recognition
- ---
- ## ποΈ Repository Structure
- ```
- MinerU-Ecosystem/
- βββ cli/ # Command-line tool for document parsing
- βββ sdk/ # Multi-language SDKs
- β βββ python/ # Python SDK
- β βββ go/ # Go SDK
- β βββ typescript/ # TypeScript SDK
- βββ langchain_mineru/ # LangChain document loader integration
- βββ llama-index-readers-mineru/ # LlamaIndex document reader integration
- βββ mcp/ # Model Context Protocol server (Python)
- βββ skills/ # AI agent skills (Claude Code, OpenClaw, etc.)
- ```
- ---
- ## π Supported APIs
- All components support both API modes:
- | Comparison | π― Precision Extract API | β‘ Quick Parse API (Agent-Oriented) |
- | --------------- | ----------------------------------------------------------- | ----------------------------------- |
- | Auth | β Token required | β Not required (IP rate-limited) |
- | Model Versions | `pipeline` (default) / `vlm` (recommended) / `MinerU-HTML` | Fixed lightweight pipeline model |
- | File Size Limit | β€ 200 MB | β€ 10 MB |
- | Page Limit | β€ 200 pages | β€ 20 pages |
- | Batch Support | β Supported (β€ 200 files) | β Single file only |
- | Output Formats | Markdown, JSON, Zip; optional export to DOCX / HTML / LaTeX | Markdown only |
- ## π§ Choose Your Integration Path
- Not sure where to start? Pick the path that matches your use case:
- ```text
- I want to...
- β
- βββ π Try it instantly, with no install and no code
- β βββ Web App β https://mineru.net/OpenSourceTools/Extractor
- β
- βββ π» Parse documents from the terminal
- β βββ CLI β cli/
- β flash-extract: no token, best for quick previews
- β extract: full features, better for production workflows
- β
- βββ π Integrate it into my Python / Go / TypeScript project
- β βββ SDK β sdk/python/ | sdk/go/ | sdk/typescript/
- β
- βββ π€ Enable my AI agent to parse documents
- β βββ Call the CLI directly β cli/
- β βββ Use natural-language skills (OpenClaw, ZeroClaw, etc.) β skills/
- β βββ Use MCP protocol (Cursor, Claude Desktop, Windsurf, etc.) β mcp/
- β
- βββ π Build a RAG pipeline / knowledge base
- β βββ LangChain Loader β langchain_mineru/
- β βββ LlamaIndex Reader β llama-index-readers-mineru/
- β flash mode: zero-token quick start
- β precision mode: OCR, tables, formulas, and higher fidelity
- ```
- ---
- ## π Quick Start
- ### π» CLI (`cli/`)
- A fast command-line tool for parsing documents directly from your terminal.
- #### Installation
- ```bash
- # Linux / macOS
- curl -fsSL https://cdn-mineru.openxlab.org.cn/open-api-cli/install.sh | sh
- ```
- ```powershell
- # Windows (PowerShell)
- irm https://cdn-mineru.openxlab.org.cn/open-api-cli/install.ps1 | iex
- ```
- **Flash Extract (no login)**
- ```bash
- mineru-open-api flash-extract report.pdf
- ```
- **Precision Extract (login required)**
- ```bash
- # First-time setup
- mineru-open-api auth
- # Extract to stdout
- mineru-open-api extract paper.pdf
- # Save all resources (images/tables) to directory
- mineru-open-api extract report.pdf -o ./output/
- # Export to multiple formats
- mineru-open-api extract report.pdf -f docx,latex,html -o ./results/
- ```
- **Web Crawl**
- ```bash
- mineru-open-api crawl https://www.example.com
- ```
- **Batch Processing**
- ```bash
- # All PDFs in current directory
- mineru-open-api extract *.pdf -o ./results/
- # From a file list
- mineru-open-api extract --list filelist.txt -o ./results/
- ```
- ---
- ### π Python SDK
- #### Installation
- ```bash
- pip install mineru-open-sdk
- ```
- **Flash Extract (no token)**
- ```python
- from mineru import MinerU
- client = MinerU()
- result = client.flash_extract("https://cdn-mineru.openxlab.org.cn/demo/example.pdf")
- print(result.markdown)
- ```
- **Precision Extract (token required)**
- ```python
- from mineru import MinerU
- client = MinerU("your-api-token")
- result = client.extract("https://cdn-mineru.openxlab.org.cn/demo/example.pdf")
- print(result.markdown)
- print(result.images) # extracted image list
- ```
- ---
- ### πΉ Go SDK
- #### Installation
- ```bash
- go get github.com/opendatalab/MinerU-Ecosystem/sdk/go@latest
- ```
- **Flash Extract**
- ```go
- package main
- import (
- "context"
- "fmt"
- mineru "github.com/opendatalab/MinerU-Ecosystem/sdk/go"
- )
- func main() {
- client := mineru.NewFlash()
- result, err := client.FlashExtract(
- context.Background(),
- "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
- )
- if err != nil {
- panic(err)
- }
- fmt.Println(result.Markdown)
- }
- ```
- **Precision Extract**
- ```go
- client, err := mineru.New("your-api-token")
- if err != nil {
- panic(err)
- }
- result, err := client.Extract(
- context.Background(),
- "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
- )
- if err != nil {
- panic(err)
- }
- fmt.Println(result.Markdown)
- ```
- **Precision Extract with options**
- ```go
- result, err := client.Extract(ctx, "./paper.pdf",
- mineru.WithModel("vlm"),
- mineru.WithLanguage("en"),
- mineru.WithPages("1-20"),
- mineru.WithExtraFormats("docx"),
- mineru.WithPollTimeout(10*time.Minute),
- )
- if err != nil {
- panic(err)
- }
- if err := result.SaveAll("./output"); err != nil {
- panic(err)
- }
- ```
- **Batch Processing**
- ```go
- ch, err := client.ExtractBatch(ctx, []string{"a.pdf", "b.pdf"})
- if err != nil {
- panic(err)
- }
- for result := range ch {
- fmt.Printf("%s: %s\n", result.Filename, result.State)
- }
- ```
- **Web Crawling**
- ```go
- result, err := client.Crawl(ctx, "https://www.example.com")
- if err != nil {
- panic(err)
- }
- fmt.Println(result.Markdown)
- ```
- ---
- ### π¦ TypeScript / JavaScript SDK
- #### Installation
- ```bash
- npm install mineru-open-sdk
- ```
- **Flash Extract**
- ```typescript
- import { MinerU } from "mineru-open-sdk";
- const client = new MinerU();
- const result = await client.flashExtract(
- "https://cdn-mineru.openxlab.org.cn/demo/example.pdf"
- );
- console.log(result.markdown);
- ```
- **Precision Extract**
- ```typescript
- import { MinerU } from "mineru-open-sdk";
- const client = new MinerU("your-api-token");
- const result = await client.extract(
- "https://cdn-mineru.openxlab.org.cn/demo/example.pdf"
- );
- console.log(result.markdown);
- console.log(result.images);
- ```
- **Precision Extract with options**
- ```typescript
- import { MinerU, saveAll } from "mineru-open-sdk";
- const client = new MinerU("your-api-token");
- const result = await client.extract("./paper.pdf", {
- model: "vlm", // "vlm" | "pipeline" | "html"
- language: "en",
- pages: "1-20",
- extraFormats: ["docx"],
- timeout: 600,
- });
- await saveAll(result, "./output");
- ```
- **Batch Processing**
- ```typescript
- for await (const result of client.extractBatch(["a.pdf", "b.pdf"])) {
- console.log(`${result.filename}: ${result.state}`);
- }
- ```
- **Web Crawling**
- ```typescript
- const result = await client.crawl("https://www.example.com");
- console.log(result.markdown);
- ```
- ---
- ## π€ Use with Claude / Cursor (MCP Server)
- MinerU provides an official MCP Server allowing Claude Desktop, Cursor, Windsurf, and any MCP-compatible AI client to parse documents as a native tool.
- > No API key needed β Flash mode works out of the box, free, up to 20 pages / 10 MB per file.
- **Configure: `claude_desktop_config.json` / `.cursor/mcp.json`**
- ```json
- {
- "mcpServers": {
- "mineru": {
- "command": "uvx",
- "args": ["mineru-open-mcp"],
- "env": {
- "MINERU_API_TOKEN": "your_key_here"
- }
- }
- }
- }
- ```
- **Streamable HTTP mode (web-based MCP clients)**
- ```bash
- MINERU_API_TOKEN=your_key mineru-open-mcp --transport streamable-http --port 8001
- ```
- ```json
- {
- "mcpServers": {
- "mineru": {
- "type": "streamableHttp",
- "url": "http://127.0.0.1:8001/mcp"
- }
- }
- }
- ```
- **Tools exposed via MCP:**
- | Tool | Description |
- |---|---|
- | `parse_documents` | Convert PDF, DOCX, PPTX, images, HTML to Markdown |
- | `get_ocr_languages` | List all 109 supported OCR languages |
- | `clean_logs` | Delete old server log files (when `ENABLE_LOG=true`) |
- **Environment Variables:**
- | Variable | Description | Default |
- |---|---|---|
- | `MINERU_API_TOKEN` | MinerU cloud API token | β |
- | `OUTPUT_DIR` | Directory for saved output | `~/mineru-downloads` |
- | `ENABLE_LOG` | Set `true` to write log files | disabled |
- | `MINERU_LOG_DIR` | Override log file directory | `~/.mineru-open-mcp/logs/` |
- ---
- ## π¦ Use in RAG with LangChain
- `langchain-mineru` is an official LangChain Document Loader β parse any document into LangChain `Document` objects with one line of code.
- #### Installation
- ```bash
- pip install langchain-mineru
- ```
- **Minimal example (no token)**
- **1. Basic usage (`flash` mode by default, no token required)**
- ```python
- from langchain_mineru import MinerULoader
- loader = MinerULoader(source="demo.pdf") # flash mode, no token needed
- docs = loader.load()
- print(docs[0].page_content[:500])
- print(docs[0].metadata)
- ```
- Default is `mode="flash"`, which is ideal for quick previews and lightweight integrations.
- **2. Precision mode (token required)**
- Best for long documents, larger files, and workflows that need higher-fidelity extraction or standard API outputs. Flash mode also supports OCR, table, and formula switches within flash API limits.
- ```python
- from langchain_mineru import MinerULoader
- loader = MinerULoader(
- source="/path/to/manual.pdf",
- mode="precision",
- token="your-api-token", # or set MINERU_TOKEN
- split_pages=True,
- pages="1-5",
- )
- docs = loader.load()
- for doc in docs:
- print(doc.metadata.get("page"), doc.page_content[:200])
- ```
- **3. Use it in a LangChain RAG pipeline**
- ```python
- from langchain_mineru import MinerULoader
- from langchain_text_splitters import RecursiveCharacterTextSplitter
- from langchain_openai import OpenAIEmbeddings
- from langchain_community.vectorstores import FAISS
- loader = MinerULoader(source="demo.pdf", split_pages=True)
- docs = loader.load()
- splitter = RecursiveCharacterTextSplitter(chunk_size=1200, chunk_overlap=200)
- chunks = splitter.split_documents(docs)
- vs = FAISS.from_documents(chunks, OpenAIEmbeddings())
- results = vs.similarity_search("What are the key conclusions in this document?", k=3)
- for r in results:
- print(r.page_content[:200])
- ```
- Default is `mode="flash"` (no API token required). Switch to `mode="precision"` for higher fidelity with token auth. For RAG use cases, `split_pages=True` is usually a better default for PDFs because it gives you page-level `Document` granularity.
- ### ## Use in RAG with LlamaIndex
- A document reader for LlamaIndex that parses PDFs, Word files, PPTs, images, and Excel files through MinerU and returns LlamaIndex-compatible `Document` objects for indexing and retrieval.
- #### Installation
- ```bash
- pip install llama-index-readers-mineru
- ```
- #### Usage
- **1. Flash mode (default, no token required)**
- Good for quick setup and lightweight parsing. Output is returned as Markdown.
- ```python
- from llama_index.readers.mineru import MinerUReader
- reader = MinerUReader()
- documents = reader.load_data("https://cdn-mineru.openxlab.org.cn/demo/example.pdf")
- print(documents[0].text[:500])
- print(documents[0].metadata)
- ```
- **2. Precision mode (token required)**
- Best for longer documents, larger files, and use cases that need higher-fidelity extraction or standard API outputs. Flash mode also supports OCR, formula, and table switches within flash API limits.
- ```python
- from llama_index.readers.mineru import MinerUReader
- reader = MinerUReader(
- mode="precision",
- token="your-api-token", # or set MINERU_TOKEN
- pages="1-20",
- )
- documents = reader.load_data("/path/to/paper.pdf")
- ```
- **3. Use it in a LlamaIndex pipeline**
- ```python
- from llama_index.core import VectorStoreIndex
- from llama_index.readers.mineru import MinerUReader
- reader = MinerUReader(split_pages=True)
- documents = reader.load_data("/path/to/paper.pdf")
- index = VectorStoreIndex.from_documents(documents)
- query_engine = index.as_query_engine()
- response = query_engine.query("Summarize the main findings of this document")
- print(response)
- ```
- Default is `mode="flash"` with no token required. Switch to `mode="precision"` when you need higher parsing fidelity. For PDF-based RAG pipelines, `split_pages=True` is recommended so each page becomes a separate `Document`.
- ---
- ## π€ AI Agent Skills (`skills/`)
- Pre-built skills for AI coding agents, wrapping the `mineru-open-api` CLI for use in agent workflows.
- - **[OpenClaw / ClawHub](https://clawhub.ai/MinerU-Extract/mineru-ai)** β View skill details
- - **[One-click download](https://cdn-mineru.openxlab.org.cn/open-api-cli/skill.zip)** β Skill package
- - Compatible with Claude Code, OpenClaw, ZeroClaw, and other skill-interface agents
- ---
- ## π All Integrations
- | Framework / Tool | Status | Notes |
- |---|---|---|
- | LangChain | β Official | `pip install langchain-mineru` |
- | LlamaIndex | β Community | See MinerU-Ecosystem |
- | RAGFlow | β Supported | Document loader integration |
- | RAG-Anything | β Supported | Multi-modal RAG pipeline |
- | Flowise | β Supported | Node-based RAG builder |
- | Dify | β Native Plugin | Built-in document loader |
- | FastGPT | β Native Plugin | Integration guide |
- | Claude Desktop | β MCP | `uvx mineru-open-mcp` |
- | Cursor | β MCP | `.cursor/mcp.json` config |
- | Windsurf | β MCP | stdio / streamable-http |
- | OpenClaw / ZeroClaw | β Agent Skill | ClawHub |
- | Go SDK | β Official | `go get .../sdk/go@latest` |
- | TypeScript SDK | β Official | `npm install mineru-open-sdk` |
- | Python SDK | β Official | `pip install mineru-open-sdk` |
- ---
- ## π Documentation
- | Resource | Link |
- |---|---|
- | MinerU Open API Docs | [mineru.net/apiManage/docs](https://mineru.net/apiManage/docs) |
- | MinerU Online Demo | [mineru.net/OpenSourceTools/Extractor](https://mineru.net/OpenSourceTools/Extractor) |
- | MinerU Open Source | [github.com/opendatalab/MinerU](https://github.com/opendatalab/MinerU) |
- ---
- ## π License
- This project is licensed under the [Apache License 2.0](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.