mineru-docparse-mcp

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

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:

Backend Options

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.

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