# MinerU MCP

> MinerU MCP is an open-source MCP server for files and documents. Parse PDFs, Office files and images to Markdown with tables and LaTeX, self-hosted. It runs locally on your machine and is started by your AI client.

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

## About

This server is a thin MCP adapter in front of a MinerU API that you run yourself. The agent sends a document by local path or as Base64 and gets back Markdown with headings, HTML tables and LaTeX equations; the heavy parsing models stay on your own hardware and the MCP client installs nothing like PyTorch. The README is written in Spanish with an English version.

parse_document runs synchronously, typically 30 to 120 seconds, for PDF, DOCX, PPTX, XLSX or images. submit_parse_task starts an asynchronous job for documents over about 50 pages, with get_task_status and get_task_result to follow it, and mineru_health reports whether the backend is up, asleep from inactivity or broken. Options include backend (pipeline needs about 1.5 GB of VRAM, hybrid-engine and vlm-engine about 4 GB), parse method, OCR language, formula and table switches and zero-based page ranges. With hybrid-engine, high effort and image analysis, figures can be turned into Mermaid diagrams.

It runs over HTTP on port 8202 for a shared server, with an optional bearer token, or over stdio through Docker or uvx. For privacy it only sends documents to a loopback or host.docker.internal address and refuses any other MinerU URL. It does not include mineru-api or the models, and can start mineru-api through systemd if it is stopped.

## Features

- **Document to Markdown:** Converts PDF, DOCX, PPTX, XLSX and images with tables and LaTeX.
- **Async parsing:** submit_parse_task and task tools handle long documents.
- **Selectable backends:** Choose pipeline, hybrid-engine or vlm-engine by VRAM and accuracy.
- **Page ranges:** Parse only chosen pages, counted from 0.
- **Local-only guard:** Refuses to send documents to a non-loopback MinerU host.
- **Health check:** Distinguishes a sleeping backend from a broken one.

## Good for

- Convert research papers with equations into RAG-ready Markdown
- Extract tables from a long report asynchronously
- Share one GPU-backed parser across a team of agents
- Parse a few pages of a large PDF
- Turn figures into Mermaid diagrams

## Install

### Claude Code (Terminal)

```sh
claude mcp add mineru-mcp -- docker run -i --rm ghcr.io/germaniu/mineru-mcp:0.1.0
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "mineru-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/germaniu/mineru-mcp:0.1.0"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "mineru-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/germaniu/mineru-mcp:0.1.0"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "mineru-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/germaniu/mineru-mcp:0.1.0"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "mineru-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/germaniu/mineru-mcp:0.1.0"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "mineru-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/germaniu/mineru-mcp:0.1.0"
      ]
    }
  }
}
```

## Tools

- `parse_document`: Synchronous parse of a PDF, DOCX, PPTX, XLSX or image to Markdown.
- `submit_parse_task`: Starts an asynchronous parse and returns a task_id.
- `get_task_status`: Returns pending, processing, completed or failed.
- `get_task_result`: Returns the Markdown of a completed task.
- `mineru_health`: Reports availability, version and queued tasks of mineru-api.

## FAQ

### Does it include the MinerU engine?

No. mineru-api and the models are installed separately on the host.

### Are documents sent to the cloud?

No. Only loopback or host.docker.internal MinerU URLs are accepted.

### How much GPU memory does it need?

About 1.5 GB for the pipeline backend and about 4 GB for hybrid-engine or vlm-engine.

### How do I run it?

Over HTTP on port 8202, or over stdio with Docker or uvx.

### Is MinerU MCP free?

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

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

Run this command in your terminal: claude mcp add mineru-mcp -- docker run -i --rm ghcr.io/germaniu/mineru-mcp:0.1.0

### What are the best alternatives to MinerU MCP?

The closest alternatives to MinerU MCP 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-mcp
