活水 PDF 转换器 (Huoshui PDF Converter)

A high-quality, cross-platform PDF ↔ Markdown converter implemented as an MCP (Model Context Protocol) server. Supports bidirectional conversion with full Unicode/CJK character support.

Features

Core Capabilities

• PDF → Markdown: Extract text and images with layout preservation
• Markdown → PDF: Generate beautiful PDFs with multiple rendering engines
• Unicode Support: Full support for Chinese, Japanese, Korean, and other Unicode characters
• Cross-Platform: Works on Windows, macOS, and Linux
• MCP Integration: Use with Claude Desktop or any MCP-compatible client

Technical Features

• Pure Python: No external system dependencies required
• Automatic Font Detection: Finds and uses system Unicode fonts
• Smart Engine Selection: Automatically switches engines based on content
• Comprehensive Error Handling: Graceful degradation and detailed logging
• Async Architecture: Non-blocking operations for better performance

Installation

From MCP Registry (Recommended)

This server is available in the Model Context Protocol Registry. Install it using your MCP client.

mcp-name: io.github.huoshuiai42/huoshui-pdf-converter

As a Python Package

pip install huoshui-pdf-converter

Or using uv (recommended):

uv pip install huoshui-pdf-converter

As an MCP Server

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

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

Or if you prefer to use a specific Python environment:

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

Usage

Command Line Interface

# Convert PDF to Markdown
huoshui-pdf pdf-to-md input.pdf output.md

# Convert Markdown to PDF
huoshui-pdf md-to-pdf input.md output.pdf

# With options
huoshui-pdf md-to-pdf input.md output.pdf --page-size A4 --margin 2cm --font-size 12

As a Python Library

import asyncio
from huoshui_pdf_converter import PDFToMarkdownConverter, MarkdownToPDFConverter

async def main():
    # PDF to Markdown
    pdf_converter = PDFToMarkdownConverter()
    result = await pdf_converter.convert(
        pdf_path="input.pdf",
        output_path="output.md",
        extract_images=True,
        preserve_formatting=True
    )

    # Markdown to PDF
    md_converter = MarkdownToPDFConverter()
    result = await md_converter.convert(
        markdown_path="input.md",
        output_path="output.pdf",
        page_size="A4",
        margin="2cm",
        font_size=12
    )

asyncio.run(main())

MCP Tools

When used as an MCP server, the following tools are available:

1. pdf_to_markdown: Convert PDF files to Markdown

   {
     "pdf_path": "path/to/input.pdf",
     "output_path": "path/to/output.md",
     "extract_images": true,
     "preserve_formatting": true
   }
   

2. markdown_to_pdf: Convert Markdown files to PDF

   {
     "markdown_path": "path/to/input.md",
     "output_path": "path/to/output.pdf",
     "page_size": "A4",
     "margin": "2cm",
     "font_size": 12
   }
   

3. list_supported_formats: Get s

... View full README on GitHub