# linxule/mineru-mcp [Health: Active]

**Category:** 🔎 Search & Data Extraction  
**Repository:** https://github.com/linxule/mineru-mcp  
**GitHub Stars:** 9  
**npm Downloads (last month):** 575  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/linxule-mineru-mcp

## Description
MCP server for MinerU document parsing API. Parse PDFs, images, DOCX, and PPTX with OCR (109 languages), batch processing (200 docs), page ranges, and local file upload. 73% token reduction with structured output.

## Tools
Capabilities this server exposes over MCP:

- **mineru_parse** — Parse a document URL
- **mineru_status** — Check task progress, get download URL
- **mineru_batch** — Parse multiple URLs (max 200)
- **mineru_batch_status** — Get batch results with pagination
- **mineru_upload_batch** — Upload local files for batch parsing
- **mineru_download_results** — Download results as named markdown files

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mineru-mcp": {
    "command": "npx",
    "args": ["-y","mineru-mcp"],
    "env": {
      "MINERU_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `MINERU_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/linxule-mineru-mcp/readme_