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.

pymupdf4llm-mcp ships as a Python package and can be run instantly with uvx — no virtual environment setup, no global install. The steps below take you from zero to a working PDF-to-Markdown tool inside your MCP client.
1

Prerequisites

You need two things before you start:That’s it. uvx downloads and runs pymupdf4llm-mcp in an isolated environment on first use, so there is nothing else to install globally.
2

Launch the MCP server

Choose the transport mode that fits your workflow and run the corresponding command:
uvx pymupdf4llm-mcp@latest stdio
  • stdio — starts the server and keeps it attached to the current terminal process. Most local MCP clients (Cursor, Windsurf, Claude Desktop) manage this process for you automatically — you typically don’t need to run this command manually.
  • sse — starts an HTTP server on http://localhost:3000 that clients connect to over the network. Keep this process running in the background while your client is active.
If you want the SSE server on a different host or port, pass --host and --port flags:
uvx pymupdf4llm-mcp@latest sse --host 0.0.0.0 --port 8080
3

Configure your MCP client

Open your MCP client’s configuration file and add the pymupdf4llm-mcp server block. The exact file location varies by client (e.g. .cursor/mcp.json for Cursor, ~/.config/windsurf/mcp.json for Windsurf, ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop on macOS), but the JSON structure is the same.
{
  "mcpServers": {
    "pymupdf4llm-mcp": {
      "command": "uvx",
      "args": ["pymupdf4llm-mcp@latest", "stdio"],
      "env": {}
    }
  }
}
With the stdio config, the client spawns the server process automatically each session — no manual launch needed. With the sse config, the client connects to the already-running HTTP server you started in the previous step.Restart your MCP client after saving the configuration so it picks up the new server.
4

Invoke the tool

Once the server is registered, ask your LLM client to convert a PDF using plain language:
“Convert /home/alice/docs/report.pdf to Markdown.”
The client resolves this to the following tool call behind the scenes:
{
  "tool": "convert_pdf_to_markdown",
  "arguments": {
    "file_path": "/home/alice/docs/report.pdf"
  }
}
You can also direct the model to extract images or save the output to a file:
{
  "tool": "convert_pdf_to_markdown",
  "arguments": {
    "file_path": "/home/alice/docs/report.pdf",
    "image_path": "/home/alice/docs/images",
    "save_path": "/home/alice/docs/report.md"
  }
}
file_path, image_path, and save_path must all be absolute paths. If you pass a relative path the tool will return a file-not-found error. When prompting your LLM client, always provide the full path to your PDF.
5

Check the output

The tool returns different responses depending on whether you supplied save_path:Without save_path (inline) — The Markdown content is returned directly in the tool response under the markdown_content key. The model can read it immediately and answer questions about the document.With save_path (file) — The tool writes the full Markdown to the specified file and returns the resolved absolute path under markdown_path. Use this for anything you want to keep on disk or process further.
Inline responses are truncated at 10,000 characters. If your PDF produces more Markdown than that, the response will end with ... (truncated) and a tip instructing you to use save_path. Pass an absolute save_path to get the complete, un-truncated output in a file that you or the model can read in parts.
A successful inline response looks like this:
{
  "success": true,
  "markdown_content": "# Report Title\n\n...",
  "tips": "All content is returned."
}
A successful file-save response looks like this:
{
  "success": true,
  "markdown_path": "/home/alice/docs/report.md"
}

​
Next steps

With the server running and your client configured, you’re ready to go deeper:

Build docs developers (and LLMs) love

Get started for freeTalk to us