Convert To Markdown

Document to Markdown Conversion

Convert documents to Markdown using the mineru-converter MCP tools. Supports URLs and local file paths. The server auto-detects file type and configures optimal settings (model, OCR, etc.).

MCP Tools Reference

Primary tool — use this by default

• convert_to_markdown — Complete workflow: submit → poll → download. Parameters:
• url (required): URL or local file path
• output_path (required): local path to save the result zip (e.g., ./temp/report.zip)
• model_version (optional, default "vlm"): auto-detected; "MinerU-HTML" for HTML files
• max_wait_seconds (optional, default 300): increase for large documents (e.g., 600 for 100+ page PDFs)
• poll_interval (optional, default 10)
• convert_pdf_to_markdown is an identical alias

Step-by-step tools — use when finer control is needed

1. create_parse_task — Submit a parsing task. Extra parameters:

• is_ocr (default false): force OCR on; auto-enabled for images
• enable_formula (default true): formula recognition
• enable_table (default true): table recognition
• Returns task_id (URL input) or batch_id (local file input)

1. get_task_status — Poll task progress. Pass task_id or batch_id.

1. download_result — Download the result zip. Parameters: zip_url, output_path.

Use step-by-step tools when the user needs to: disable formula/table recognition, force OCR, submit multiple tasks in parallel, or check a previously submitted task.

Workflow

1. Determine output path

• If the user provided an output path, use it (ensure it ends in .zip).
• Otherwise, derive from the filename: ./temp/.zip
• URL example: https://example.com/report.pdf → ./temp/report.zip
• Local example: C:\docs\slides.pptx → ./temp/slides.zip

2. Call convert_to_markdown

Pass url (the URL or local file path as-is) and output_path. The server handles:

• Local file upload via batch API automatically
• HTML → MinerU-HTML model, images → OCR enabled
• Large PDFs: >600 pages uses page ranges; >200MB splits the file into chunks
• Polling until completion or timeout

For large documents (100+ pages), set max_wait_seconds to 600 or higher.

3. Extract and read

After the zip downloads:

1. Unzip to a sibling directory (same name without .zip):

``bash unzip -o ./temp/report.zip -d ./temp/report ``

1. Find .md files inside the extracted directory.
2. Read the Markdown content.
3. Note any referenced files (e.g., ``) — ignore all other files (JSON, content_list, etc.).
4. Do NOT delete the zip file.

4. Respond

• Analysis requested: Read the Markdown and answer the user's questions or provide a summary.
• Output path specified: Confirm save location and show the exact path of the .md file(s).
• No specific request: Show the extracted Markdown path and offer to analyze the content.

Rules

1. Always use relative paths in shell commands. Never cd to an absolute path.
2. Always auto-extract zip files after download. Do not delete the zip.
3. Pass local file paths directly to the MCP tool — do not attempt to upload manually.

Error Handling

• Task creation / upload failure: Report the API error message.
• Timeout: Return the task_id or batch_id and suggest calling get_task_status to check later. Consider retrying with a higher max_wait_seconds.
• Download / extraction failure: Return the full_zip_url for manual download.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AvatarGanymede
• Source: AvatarGanymede/MinerU-MCP
• License: MIT

Install and usage instructions live in the source repository linked above.