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 always returns a JSON object. The exact shape of that object depends on two factors: whether a save_path argument was provided, and whether the conversion succeeded. Every response includes a success boolean field that MCP clients should inspect before reading any other field.
The response is always a JSON object — MCP clients should always check the success field first before accessing markdown_content, markdown_path, or any other field. Reading additional fields without first confirming success is true may yield undefined or null values.

​
Success: inline content (no save_path)

When no save_path argument is provided, the tool returns the converted Markdown directly inside the response object. If the content is very long, it is truncated to 10,000 characters.
​
success
boolean
Always true on a successful conversion.
​
markdown_content
string
The Markdown string extracted from the PDF. Truncated to 10,000 characters if the document produces output that exceeds that limit. A ... (truncated) marker is appended when truncation occurs.
​
tips
string
A hint message describing whether all content was returned.
  • When content is truncated: "The content is too long. Please use \save_path` to save the markdown file and read it partially.”`
  • When all content is returned: "All content is returned. "
{
  "success": true,
  "markdown_content": "# Report Title\n\nSection content...",
  "tips": "All content is returned. "
}

​
Success: file saved (with save_path)

When a save_path argument is provided, the tool writes the full Markdown to disk and returns the resolved absolute path to the written file instead of the Markdown string.
​
success
boolean
Always true on a successful conversion.
​
markdown_path
string
The absolute path to the written Markdown file, resolved to a canonical path on the server’s filesystem.
{
  "success": true,
  "markdown_path": "/home/user/documents/report.md"
}

​
Error response

When a recoverable error occurs — such as a missing file or a conversion exception — the tool returns an error object instead of raising an exception to the MCP client.
​
success
boolean
Always false when an error occurs.
​
error
string
A human-readable message describing what went wrong. The message includes the specific file path or underlying exception message where applicable.
File not found: 
{
  "success": false,
  "error": "File not found: /home/user/missing.pdf"
}
Conversion failure: 
{
  "success": false,
  "error": "Failed to convert PDF to markdown: <exception message>"
}

​
10,000-character truncation

When the tool is called without a save_path and the converted Markdown exceeds 10,000 characters, the response content is cut at the 10,000-character boundary and a truncation marker is appended. The resulting markdown_content value looks like this: 
# ... first 10,000 characters of markdown ...

... (truncated)
The tips field simultaneously changes to prompt the caller to retry with a save_path. To avoid truncation entirely, supply a save_path when working with large or multi-page PDFs. The full content will be written to disk and can then be read in sections. For full parameter details and calling examples, see convert_pdf_to_markdown.

Build docs developers (and LLMs) love

Get started for freeTalk to us