Which integrations are available for this server?

Provides tools for converting PDF to Markdown and Markdown to PDF, enabling AI agents to work with Markdown documents.

How do I use huoshui-pdf-converter?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@huoshui-pdf-converter convert report.pdf to markdown" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

huoshui-pdf-converter

Official

by huoshuiai42

Overview Schema Related Servers Score Discussions

Python

Local

活水 PDF 转换器 (Huoshui PDF Converter)

License: MIT Python 3.10+ MCP PyPI version

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

Related MCP server: PDF2MD MCP Server

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:

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
}

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
}

list_supported_formats: Get supported formats and engines
validate_file: Validate input files before conversion

Supported Formats

Input Formats

PDF: All standard PDF files (PDF 1.0 - 1.7)
Markdown: CommonMark and GitHub Flavored Markdown

Output Options

Page Sizes: A4, A3, Letter, Legal
Margins: Customizable (e.g., "1cm", "0.5in")
Font Sizes: Any size in points
Images: PNG, JPEG extraction from PDFs

Unicode and Font Support

The converter automatically detects and uses appropriate fonts for different languages:

macOS: Arial Unicode, PingFang SC, STHeiti
Windows: Microsoft YaHei, SimSun, Arial Unicode MS
Linux: Noto Sans CJK, Source Han Sans, WenQuanYi

Architecture

Conversion Engines

PDF → Markdown

PyMuPDF (MuPDF): High-quality text and image extraction

Markdown → PDF

ReportLab: Best Unicode support, cross-platform compatibility
xhtml2pdf: Good HTML/CSS rendering (fallback)
fpdf2: Basic PDF generation (last resort)

Engine Selection Logic

Detects CJK characters → Uses ReportLab
Complex formatting → Uses xhtml2pdf
Basic documents → Uses any available engine

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/yourusername/huoshui-pdf-converter.git
cd huoshui-pdf-converter

# Install dependencies
uv pip install -e ".[dev]"

# Run tests
python test_converter.py

Project Structure

huoshui-pdf-converter/
├── huoshui_pdf_converter/
│   ├── __init__.py
│   ├── server.py           # MCP server implementation
│   ├── pdf_converter.py    # PDF to Markdown converter
│   └── markdown_converter.py # Markdown to PDF converter
├── pyproject.toml
├── README.md
├── LICENSE
└── test_converter.py

Troubleshooting

Common Issues

Chinese characters not displaying:
- Ensure Arial Unicode or similar fonts are installed
- The converter will automatically detect and use appropriate fonts
Import errors:
- Install all dependencies: pip install huoshui-pdf-converter[all]
MCP connection issues:
- Check Claude Desktop logs
- Ensure Python is in your PATH

Logging

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with FastMCP for Model Context Protocol support
Uses PyMuPDF for PDF parsing
Uses ReportLab for PDF generation
Inspired by the need for better PDF ↔ Markdown conversion tools

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: your.email@example.com

Available Tools

4 tools

list_supported_formatsA

List supported file formats and conversion options.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden of behavioral disclosure. It only states the purpose ('List supported file formats and conversion options') without describing what the output looks like, whether it returns a paginated list, or if there are any side effects. Since it is a read-only list operation, the behavior is implicitly safe, but the description does not elaborate beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, succinct sentence with no unnecessary words. It front-loads the action ('List') and clearly states the object. It is appropriately sized for a simple tool with no parameters and an output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, no parameters, and the presence of an output schema, the description is sufficient for an agent to understand its purpose. The output schema will describe the return values, and the sibling tool names make it clear that this is a discovery tool. No additional context is necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool accepts no parameters, so the baseline is 4. The description does not need to explain parameter semantics because there are none. The schema confirms zero parameters and 100% coverage, leaving nothing ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('List') and resource ('supported file formats and conversion options'). It distinguishes itself from sibling tools (pdf_to_markdown, markdown_to_pdf, validate_file) by being an information/discovery tool rather than a converter or validator.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings. It does not mention that one might use this tool before converting to see available options, nor does it state any exclusions. There is no 'when to use' or 'use this instead of...' context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

markdown_to_pdfB

Convert Markdown file to PDF format.

ParametersJSON Schema

Name	Required	Default
`margin`	No	1cm
`font_size`	No
`page_size`	No	A4
`output_path`	No
`markdown_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of disclosing behavior. It only states the conversion action without mentioning side effects, output file handling, overwrite behavior, required permissions, or any errors. This is a significant gap for a tool that creates a file on the filesystem.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one short sentence with zero filler words. It front-loads the core purpose without extraneous detail, making it highly concise. It is an efficient use of words, not under-specified to the point of being meaningless (unlike a single verb like 'process').

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This tool has 5 parameters, no annotations, and an output schema, but the description is too sparse to provide complete context. It does not explain how parameters interact, what the output schema contains, or any prerequisites. For a nontrivial tool with multiple configurable options, the description is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no parameter-specific meaning. While parameter names like margin, font_size, and page_size are somewhat self-explanatory, the description does not explain formats, units, or how output_path defaults to null. It fails to compensate for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool converts Markdown files to PDF format, using a specific verb ('Convert') and resource ('Markdown file' to 'PDF format'). It distinguishes itself from sibling tools like pdf_to_markdown (which does the reverse) and list_supported_formats/validate_file by stating the exact conversion direction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the conversion direction: use this when you need to turn Markdown into PDF. However, the description does not explicitly mention alternatives or exclusions, such as when to prefer pdf_to_markdown or check supported formats first. It gives no explicit when-to-use guidance beyond the basic purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pdf_to_markdownC

Convert PDF file to Markdown format.

ParametersJSON Schema

Name	Required	Description	Default
`pdf_path`	Yes
`output_path`	No
`extract_images`	No
`preserve_formatting`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description only restates the basic conversion without disclosing behavior around image extraction, formatting preservation, error handling, or output characteristics. With no annotations, this leaves the agent uninformed about edge cases and side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, but it is under-specified for a tool with four parameters. While it does not waste words, it lacks structured information needed for effective tool invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has four parameters, an output schema, and no annotations, the description is insufficiently complete. It does not cover parameter behavior, side effects, or output characteristics, making it barely adequate for an agent to understand the full context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not mention any of the four parameters (pdf_path, output_path, extract_images, preserve_formatting) or their semantic meaning. Since schema description coverage is 0%, the description fails to compensate for the lack of parameter guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (convert) and the resource transformation (PDF to Markdown), which is specific and distinguishes it from the sibling tools like markdown_to_pdf and list_supported_formats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly conveys when to use this tool (when you need Markdown from a PDF) but does not explicitly mention alternatives or exclusions. It provides the core purpose but lacks direct comparison to siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_fileC

Validate file format and convertibility.

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description is the sole source of behavioral info. It only states the action ('validate file format and convertibility') without disclosing what happens on invalid files, whether any side effects occur, or supported input constraints. This is a minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It is front-loaded and easy to parse, though it lacks any additional structure. For such a brief description, conciseness is strong.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool being simple (one parameter) and having an output schema, the description omits essential context such as accepted file formats, validation criteria, and error behavior. Without annotations or richer description, the tool is not adequately specified for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage for its single parameter, and the description does not mention file_path or its expected format. The parameter name is self-explanatory, but the description fails to compensate for the schema gap, leaving semantics under-specified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('validate') and identifies the resource ('file format and convertibility'), which distinguishes it from sibling conversion tools like pdf_to_markdown and markdown_to_pdf. However, it doesn't specify what 'valid' means or what formats are involved, so it's not fully precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, exclusions, or example scenarios. Usage context must be inferred from the tool name and sibling list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: conversion in each direction, format listing, and validation. There is no overlap between converting and validating; even the two conversion tools are exact opposites.

Naming Consistency4/5

Tool names are consistent in style, with conversion tools following a 'format_to_format' pattern and utility tools using verb_noun. While not uniform across all four, the patterns are predictable and unambiguous.

Tool Count5/5

Four tools is appropriate for a focused PDF/Markdown converter: the core operations (two conversions) plus essential support (listing formats and validation). No tool is redundant.

Completeness5/5

The tool set fully covers the conversion lifecycle: users can discover supported formats, validate inputs, and convert in either direction. There are no obvious missing operations within the scope.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

PDF to Markdown (pdf2md.dev)
dev.pdf2md
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
AI & Machine Learning Image & Video Processing
2
Mdkit A
online.mdkit
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Developer Tools RAG Systems Data Platforms
31
inktomd MCP Server A
io.github.hadirizvi093
Convert files, URLs, and documents to clean, AI-ready Markdown via MCP.
File Systems Web Scraping Documentation Access
91
PDF Redaction MCP A
com.pdf-redaction
MCP server for detecting and redacting PII (Personally Identifiable Information) in PDF documents.
File Systems Security
23

Related MCP Servers

pymupdf4llm-mcp
Documentation Access Text Summarization App Automation
ai-zerolab
A
license
A
quality
F
maintenance
An MCP server that exports PDF documents to markdown format optimized for LLM processing.
Updated a year ago (2025-04-24 16:44 UTC)
1
1
BSD 3-Clause
PDF2MD MCP Server
Text Summarization Documentation Access App Automation
gavinHuang
A
license
A
quality
D
maintenance
An MCP server that converts PDF files to Markdown format using AI sampling capabilities, supporting both local files and URLs with incremental conversion features.
Updated a year ago (2025-07-04 12:49 UTC)
1
1
MIT
MD-PDF MCP Server
Developer Tools File Systems
kareemaly
F
license
A
quality
D
maintenance
An MCP server that enables bidirectional conversion between Markdown and PDF formats, including text extraction from specific pages and metadata retrieval. It supports customizable PDF output sizes and document processing through standard MCP tools.
Updated a year ago (2025-06-26 16:46 UTC)
5
1
flexberry-markitdown-mcpofficial
Multimedia Processing Developer Tools
Flexberry
A
license
Not graded
quality
C
maintenance
MCP server for converting various file formats (PDF, DOCX, images, audio, etc.) to Markdown using Microsoft MarkItDown, with support for large files and Cyrillic text.
Updated 3 months ago (2026-06-05 19:50 UTC)
1
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/huoshuiai42/huoshui-pdf-converter'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

活水 PDF 转换器 (Huoshui PDF Converter)

Features

Core Capabilities

Technical Features

Installation

From MCP Registry (Recommended)

As a Python Package

As an MCP Server

Usage

Command Line Interface

As a Python Library

MCP Tools

Supported Formats

Input Formats

Output Options

Unicode and Font Support

Architecture

Conversion Engines

Engine Selection Logic

Development

Setup Development Environment

Project Structure

Troubleshooting

Common Issues

Logging

Contributing

License

Acknowledgments

Support

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

flexberry-markitdown-mcpofficial

Latest Blog Posts

MCP directory API