# MinerU

> MinerU is an open-source MCP server for files and documents. Parse PDFs, images, DOCX and PPTX to Markdown with the MinerU cloud API, with OCR. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Linux, Windows
- **Repository:** https://github.com/linxule/mineru-mcp
- **MCP Registry name:** io.github.linxule/mineru
- **Categories:** [files and documents](https://ai-powered.com/categories/files-and-documents)
- **Listing updated:** 2026-11-18

## About

This server and its companion mineru-cloud CLI wrap the MinerU document-parsing API, and the README stresses keeping everything: complete result archives, durable local operation journals and portable PDF bundles. It needs a MinerU API key and Node.js 20 or newer (the README recommends 24), and version 1.x stays available for Node 18.

Parsing can use a vision-language model or the pipeline model, with language and OCR options for the latter, page ranges, batches of URLs, and uploads of local files. For long documents, mineru_parse_long submits page-range slices and mineru_merge_slices stitches the Markdown back together while retaining the slice archives. Submissions can be journaled with duplicate-request protection and resumed after interruptions; remote cancellation is not supported.

An offline command builds a portable Scholia bundle from a provider ZIP and the source PDF, with no credentials. Local retention and bundles need macOS or Linux and fail closed on Windows. ChatGPT cannot use it directly because it is a local stdio server.

## Features

- **Two parsing models:** Vision-language or pipeline model, with language and OCR options.
- **Batch and upload:** Parse many URLs or upload local files in one request.
- **Long documents:** Slice by page range, then merge the Markdown.
- **Durable operations:** Journal, resume and check submissions with duplicate protection.
- **Portable bundles:** Validate and return retained archives, offline if needed.
- **CLI twin:** mineru-cloud exposes every tool as a shell command.

## Good for

- Convert a research PDF to Markdown
- Batch-parse a folder of scanned documents
- Process a 500-page book in slices
- Archive parsing output with original filenames

## Install

### Claude Code (Terminal)

```sh
claude mcp add mineru -- npx -y mineru-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "mineru": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mineru-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `mineru_parse`: Parse a document URL
- `mineru_status`: Check task progress and get download URL
- `mineru_batch`: Parse multiple URLs
- `mineru_batch_status`: Get batch results with pagination
- `mineru_upload_batch`: Upload local files for batch parsing
- `mineru_download_results`: Retain archives and create named copies
- `mineru_parse_long`: Submit a long document as page-range slices
- `mineru_merge_slices`: Join Markdown from slices
- `mineru_capabilities`: Read known capabilities
- `mineru_submit`: Submit with a durable local journal
- `mineru_operation_status`: Read a recorded operation
- `mineru_resume`: Continue recorded checkpoints
- `mineru_cancel`: Stop local processing
- `mineru_bundle`: Validate and return a retained bundle

## FAQ

### What do I need to run it?

A MinerU API key and Node.js 20 or newer, started with npx -y mineru-mcp.

### Can I use it in ChatGPT?

Not directly. ChatGPT supports only remote HTTPS MCP servers and this one is local stdio.

### Does it work on Windows?

The server runs there with a cmd wrapper, but local retention, bundles and durable operations require macOS or Linux.

### Can I cancel a remote parse?

No. mineru_cancel stops local processing only; remote cancellation is unsupported.

### Is MinerU free?

Yes. MinerU is open source, so you can use and self-host it for free.

### How do I add MinerU to Claude Code?

Run this command in your terminal: claude mcp add mineru -- npx -y mineru-mcp

### What are the best alternatives to MinerU?

The closest alternatives to MinerU are SSRS2, Csv, Google_sheets, Onedrive and Zovo Spreadsheet Compare.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [SSRS2](https://ai-powered.com/mcp/ssrs2): SSRS2 is an MCP server for files and documents.
- [Csv](https://ai-powered.com/mcp/csv): Csv is a freemium MCP server for files and documents.
- [Google_sheets](https://ai-powered.com/mcp/google-sheets-3): Google_sheets is a freemium MCP server for files and documents.
- [Onedrive](https://ai-powered.com/mcp/onedrive): Onedrive is a freemium MCP server for files and documents.
- [Zovo Spreadsheet Compare](https://ai-powered.com/mcp/zovo-spreadsheet-compare): Zovo Spreadsheet Compare is an MCP server for files and documents.
- [Video to Audio Converter MCP](https://ai-powered.com/mcp/video-to-audio-converter-mcp): Video to Audio Converter MCP is a free MCP server for design and media.
- [Google_drive](https://ai-powered.com/mcp/google-drive-5): Google_drive is a freemium MCP server for files and documents.
- [Markdown](https://ai-powered.com/mcp/markdown-2): Markdown is a freemium MCP server for files and documents.

---
Source: https://ai-powered.com/mcp/mineru
