Mineru Docparse

MCP Server that converts Word / PDF / PPT / Excel to Markdown, powered by the MinerU DocParse API.

This project is a protocol wrapper — it does not parse documents itself. You need a running MinerU DocParse service, defaulting to http://localhost:8000. See the MinerU repository for deployment instructions.

Installation

pip install mineru-docparse-mcp

Setup with Claude Code

The output directory is a server-side setting (not a per-request parameter), so MINERU_OUTPUT_DIR must be configured in advance:

{
  "mcpServers": {
    "mineru": {
      "command": "uvx",
      "args": ["mineru-docparse-mcp"],
      "env": {
        "MINERU_API_URL": "http://localhost:8000",
        "MINERU_OUTPUT_DIR": "/Users/yourname/Documents/mineru-output"
      }
    }
  }
}

Once configured, Claude will automatically invoke the tools below. All parsed results are saved to MINERU_OUTPUT_DIR.

Tools

Tool	Description
mineru_parse_document	Convert PDF/Word/PPT/Excel to Markdown, saved to disk
mineru_health_check	Check MinerU service health

Output format: Results are saved exactly as returned by MinerU. When response_format_zip=true (the default) output is saved as .zip; when false as .json. File name matches the source file — if a file with the same name already exists, a timestamp is appended to avoid overwriting.

API Parameters

mineru_parse_document mirrors the MinerU /file_parse endpoint:

Parameter	Type	Default	Description
file_path	string	required	Local document path (absolute or relative)
backend	enum	hybrid-engine	Parsing backend, see "backend options" below
lang_list	string[]	["ch"]	OCR language list, only for pipeline backend
effort	medium | high	medium	hybrid backends only. medium: faster, no chart analysis; high: higher accuracy with chart analysis, slower
parse_method	auto | txt | ocr	auto	PDF parsing method for pipeline/hybrid: auto-detect / text extraction / OCR
formula_enable	bool	true	Enable formula parsing (LaTeX)
table_enable	bool	true	Enable table parsing
image_analysis	bool	true	Enable image/chart analysis (VLM/hybrid backends only)
server_url	string | null	null	OpenAI-compatible server URL, required for *-http-client backends
return_md	bool	true	Include Markdown content in response
return_middle_json	bool	false	Include intermediate JSON in response
return_model_output	bool	false	Include raw model output JSON in response
return_content_list	bool	false	Include content list JSON in response
return_images	bool	false	Include extracted images in response
response_format_zip	bool	true (this project's default; API default is false)	Return results as ZIP (false returns JSON)
return_original_file	bool	false	Include processed original file in ZIP (response_format_zip=true only)
client_side_output_generation	bool	false	Defer final Markdown/content-list generation to the client
start_page_id	int	0	Starting page (0-indexed)
end_page_id	int	99999	Ending page (0-indexed)

Backend Options

Value	Description
pipeline	General-purpose, multilingual, no hallucination
vlm-engine	Local compute, high accuracy, Chinese/English only
vlm-http-client	Remote compute (OpenAI-compatible), high accuracy, Chinese/English only
hybrid-engine (default)	Local compute, hybrid parsing, multilingual, tune with effort
hybrid-http-client	Primarily remote compute + light local, hybrid parsing, multilingual

Language Options (lang_list)

ch (Chinese/English/Japanese/Traditional/Latin), ch_server, korean, ta (Tamil), te (Telugu), ka (Kannada), th (Thai), el (Greek), arabic, east_slavic, cyrillic, devanagari. Only applies to the pipeline backend; ignored by others.

Server Configuration (Environment Variables)

These are server startup settings — configure them in the env field of your MCP config, not as per-request parameters.

Variable	Default	Description
MINERU_API_URL	http://localhost:8000	MinerU service URL
MINERU_OUTPUT_DIR	none (required)	Directory for parsed results (absolute or relative paths)
MINERU_API_TIMEOUT	600	Request timeout in seconds — increase for large files
MCP_TRANSPORT	stdio	Transport mode: stdio (local subprocess) or streamable-http (remote)
MCP_HOST	127.0.0.1	Listen address (HTTP mode only); set to 0.0.0.0 to expose externally
MCP_PORT	8001	Listen port (HTTP mode only)

Remote Deployment (Optional)

To run the MCP server on a dedicated machine accessible by multiple clients, use HTTP mode:

MCP_TRANSPORT=streamable-http MCP_PORT=8001 MINERU_OUTPUT_DIR=/data/mineru-output uvx mineru-docparse-mcp

Clients connect via URL:

{
  "mcpServers": {
    "mineru": {
      "type": "streamableHttp",
      "url": "http://<server-address>:8001/mcp"
    }
  }
}

Omitting MCP_TRANSPORT defaults to local stdio mode (the "Setup with Claude Code" flow above), which is sufficient for personal use.

FAQ

"MINERU_OUTPUT_DIR environment variable not configured" — This is a required server setting, not an API parameter. Set it in the env field of your MCP config and restart the MCP connection.

"Cannot connect to MinerU service" — Verify MINERU_API_URL is reachable: curl $MINERU_API_URL/health. In stdio mode, environment variables must be set in the MCP config env field; shell export won't work.

Large files timeout — Increase MINERU_API_TIMEOUT or narrow the start_page_id/end_page_id range to parse in batches.

Want JSON instead of ZIP — Set response_format_zip to false; results will be saved as .json instead of .zip.

License

MIT