Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pymupdf/pymupdf4llm-mcp/llms.txt

Use this file to discover all available pages before exploring further.

The convert_pdf_to_markdown tool is the single tool exposed by the pymupdf4llm-mcp server. It converts a PDF file to Markdown using pymupdf4llm, extracting text, structure, and optionally images from the document. Depending on whether a save_path is provided, the tool either returns the Markdown content inline or writes it to disk and returns the file path.

​
Tool name

convert_pdf_to_markdown

​
Tool description

Converts a PDF file to markdown format via pymupdf4llm. See pymupdf.readthedocs.io/en/latest/pymupdf4llm for more. The file_path, image_path, and save_path parameters should be the absolute path to the PDF file, not a relative path. This tool will also convert the PDF to images and save them in the image_path directory. For larger PDF files, use save_path to save the markdown file then read it partially.

​
Parameters

​
file_path
string
required
Absolute path to the PDF file to convert. The path must be absolute — relative paths are not accepted.Example: /home/user/documents/report.pdf
​
image_path
string
Absolute path to the directory where extracted images will be saved. If not provided, images are saved in the same directory as the PDF file.Default: Same directory as the input PDF file.Example: /home/user/documents/images/
​
save_path
string
Absolute path for the output Markdown file. When provided, the tool writes the converted Markdown to disk and returns the file path instead of the Markdown string. Use this for large PDFs that exceed the 10,000-character inline limit.Example: /home/user/documents/report.md
All paths — file_path, image_path, and save_path — must be absolute paths. Relative paths are not supported and will produce unexpected results.

​
Usage examples

{
  "tool": "convert_pdf_to_markdown",
  "arguments": {
    "file_path": "/home/user/documents/report.pdf"
  }
}
When no save_path is provided, the tool returns the Markdown content inline. If the converted content exceeds 10,000 characters, it is truncated at that limit and a ... (truncated) marker is appended. For documents where truncation is a concern, always supply a save_path so the full content is written to disk and can be read in parts.

​
Error handling

The tool returns a JSON object with "success": false whenever a recoverable error occurs. No exceptions are raised to the MCP client. File not found — returned when file_path does not exist on disk: 
{
  "success": false,
  "error": "File not found: /home/user/documents/report.pdf"
}
Conversion failure — returned when pymupdf4llm raises an exception during processing: 
{
  "success": false,
  "error": "Failed to convert PDF to markdown: <exception message>"
}
For a complete description of all response shapes, including field definitions and truncation behavior, see Response Format.

Build docs developers (and LLMs) love

Get started for freeTalk to us