Huoshui PDF Converter

Huoshui PDF Converter is a cross‑platform MCP server that converts between PDF and Markdown, preserving text layout and Unicode characters. It enables you to integrate high‑quality PDF↔Markdown workflows into MCP clients, with automatic font handling, engine selection, and asynchronous operation for responsive performance.

How to use

You use this server by connecting through an MCP client. The converter exposes two primary actions: converting PDF files to Markdown and converting Markdown files to PDF. When you initiate a conversion, you benefit from Unicode support for CJK languages, font auto‑detection, and smart engine selection that chooses the most suitable rendering path based on content complexity.

How to install

Prerequisites: you need Python and an MCP client that can load MCP servers. You also need a JavaScript runtime if you plan to run the server via a package manager that requires it.

# Install via Python package (recommended for Python environments)
pip install huoshui-pdf-converter

# Or run through the MCP registry in your MCP client (if supported by your setup)
# No explicit commands are shown here for registry installation; use your MCP client to register the server as described in the MCP workflow.

Additional content

Configuration for MCP clients can be provided in your client’s MCP config file. The following startup configurations are shown as explicit examples for running the server locally via standard IO channels.

{
  "mcpServers": {
    "huoshui-pdf-converter": {
      "command": "uvx",
      "args": ["huoshui-pdf-converter"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "huoshui-pdf-converter": {
      "command": "python",
      "args": ["-m", "huoshui_pdf_converter.server"],
      "env": {}
    }
  }
}

Notes on usage patterns

When using as an MCP server, you can access these tools: pdf_to_markdown and markdown_to_pdf to perform conversions. You can also use list_supported_formats to discover supported formats and engines, and validate_file to verify input files before proceeding with a conversion.

Troubleshooting and tips

If you encounter issues, ensure your Python environment is properly configured and that your MCP client is able to launch the server command. For font issues affecting Unicode rendering, verify that system fonts with wide Unicode coverage are installed on your machine. Review logs for any engine‑selection messages to understand which conversion path is being used.

Available tools

pdf_to_markdown

Converts a PDF document to Markdown, extracting text and images while preserving layout.

markdown_to_pdf

Converts Markdown to a PDF document, supporting multiple rendering engines and Unicode text.

list_supported_formats

Reports the formats and engines supported by the converter.

validate_file

Validates input files before performing a conversion to catch common issues early.