Mineru MCP

What linxule/mineru-mcp MCP server does

The linxule/mineru-mcp MCP server exposes MinerU’s document parsing API as MCP tools. It is designed for extracting text, tables, and formulas from PDFs, office documents, presentations, and image files. Supported inputs include PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, and JPEG files.

Agents can submit a document URL with mineru_parse, process several URLs with mineru_batch, or upload local files through mineru_upload_batch. Parsing options include the VLM or pipeline model, page ranges, OCR, formula recognition, table recognition, language selection, and additional export formats such as HTML. OCR support covers 109 languages.

How it works

MinerU jobs run asynchronously. A single URL submission returns a task that can be tracked with mineru_status; the status response can include a download URL for the resulting archive. Batch submissions return a batch identifier, which can be checked with mineru_batch_status. Batch status supports pagination through limit and offset values and can return concise or detailed output.

For local files, the typical sequence is upload, poll for completion, and download. mineru_upload_batch can scan a directory or accept an explicit list of files. Once processing finishes, mineru_download_results writes the parsed output as Markdown files. Output names are derived from each file’s data identifier, with spaces converted to underscores, and the tool can optionally overwrite existing files.

The server selects the pipeline model by default. The VLM model is available for complex documents, while the pipeline model is intended for faster processing of simpler documents. OCR can be enabled for pipeline processing, and page ranges can limit extraction to selected pages.

Setup and configuration

The linxule/mineru-mcp MCP server requires Node.js 18 or later and a MinerU API key. Install it as a local stdio server with npx -y mineru-mcp, then provide the key through MINERU_API_KEY.

Configuration variables are:

• MINERU_API_KEY: required MinerU bearer token.
• MINERU_BASE_URL: optional API base URL; defaults to https://mineru.net/api/v4.
• MINERU_DEFAULT_MODEL: optional default model, either pipeline or vlm; defaults to pipeline.

The README provides configuration examples for Claude Desktop, Cursor, Windsurf, Cline, VS Code, and several CLI clients. ChatGPT does not directly support this local stdio setup; it requires a public HTTPS deployment using HTTP transport.

Tools and capabilities

The linxule/mineru-mcp MCP server provides these tools:

• mineru_parse: submit one document URL for parsing.
• mineru_status: inspect a task and obtain its result download URL.
• mineru_batch: submit up to 200 document URLs in one request.
• mineru_batch_status: retrieve batch results with pagination.
• mineru_upload_batch: upload local files from a directory or file list.
• mineru_download_results: save batch results as named Markdown files.

Single files are limited to 200 MB and 600 pages. The service documentation also lists a daily high-priority quota of 2,000 pages. Batch requests can contain at most 200 files.

Limitations and notes

This server depends on the MinerU API and therefore requires a valid MinerU bearer token and network access to the configured API endpoint. It does not parse files independently on the local machine. Results from URL and batch operations must be tracked before they can be downloaded.

Local upload paths and output directories must be supplied by the caller. The README uses placeholders for these paths, so they need to be replaced with paths available to the machine running the MCP client. The project is licensed under MIT.