huoshui-pdf-translator
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@huoshui-pdf-translator translate Desktop/paper.pdf to Chinese"
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 Translator
Version: 0.1.0
Powered by: FastMCP & PDFMathTranslate-next
PyPI Package: huoshui-pdf-translator
An intelligent PDF translation assistant that specializes in academic papers with mathematical formulas. Built using the FastMCP framework and powered by PDFMathTranslate-next, it provides comprehensive translation capabilities with context-aware assistance.
๐ Features
Core Translation Capabilities
๐ Academic Papers: Excellent handling of mathematical formulas and equations
๐ฌ Technical Documents: Preserves formatting and technical terminology
๐ Multi-language Support: Auto-detection with Chinese โ English specialization
๐จ Layout Preservation: Maintains original PDF structure and formatting
Smart Assistant Features
๐ง Context-Aware Prompts: Multiple specialized prompts for different scenarios
๐ ๏ธ Tool Status Checking: Verify translation tool installation and availability
๐ PDF Analysis: Get detailed information about PDF files before translation
๐ Flexible Path Handling: Support for both absolute and relative file paths
โก Progress Reporting: Real-time progress updates during translation
๐จ Intelligent Error Handling: Comprehensive error diagnosis and troubleshooting
MCP Features
๐ Resources: Translation capability listings and PDF file information
๐ฏ Tools: Translation, PDF analysis, and tool status checking
๐ฌ Prompts: Role definitions, path guidance, options explanation, and error troubleshooting
๐ Security: Safe path validation with system directory protection
Related MCP server: PDF2ZH MCP Server
๐ Quick Start
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-translator
Using uvx
uvx huoshui-pdf-translatorClaude Desktop Setup
Add this to your Claude Desktop MCP configuration:
{
"mcpServers": {
"huoshui-pdf-translator": {
"command": "uvx",
"args": ["huoshui-pdf-translator"]
}
}
}Alternative Installation Methods
Via pipx:
pipx install huoshui-pdf-translatorVia UV tools:
uv tool install huoshui-pdf-translatorClaude Desktop config for UV tools:
{
"mcpServers": {
"huoshui-pdf-translator": {
"command": "uv",
"args": ["tool", "run", "huoshui-pdf-translator"]
}
}
}๐ Usage
First-Time Setup
Warm up (downloads fonts/models): Use
warm_up_translatortoolCheck status: Use
check_translation_tooltoolTranslate: Use
translate_pdftool with your PDF path
MCP Tools
translate_pdf
Translates PDF documents while preserving mathematical formulas and layout.
# Basic usage
translate_pdf(pdf_path="Desktop/paper.pdf")
# With custom output path
translate_pdf(
pdf_path="Documents/research.pdf",
output_path="Documents/translated/research_cn.pdf"
)pdf_get
Retrieves detailed information about a PDF file.
pdf_info = pdf_get(path="Desktop/document.pdf")
# Returns: PDFResource with path, size_bytes, page_countwarm_up_translator
Downloads required assets and models. Run this first to avoid timeouts.
warm_up_translator()
# Downloads fonts and models (~50MB) for faster subsequent translationscheck_translation_tool
Verifies PDFMathTranslate-next installation and status.
status = check_translation_tool()
# Returns: status, version, messageMCP Prompts
role_and_rules: Core identity and operational rulesexplain_pdf_paths: Help with file path specificationsexplain_translation_options: Available options and best practicestroubleshoot_translation_error: Error diagnosis and solutionsexplain_translation_result: Result explanation and next steps
File Path Examples
The assistant supports flexible path specifications:
# Absolute paths
/Users/john/Desktop/research.pdf
C:\Users\John\Documents\paper.pdf
# Relative to home directory
Desktop/research.pdf
Documents/papers/study.pdf
# Simple filenames (assumes home directory)
paper.pdf๐ฏ Translation Workflow
Install:
uvx huoshui-pdf-translatorSetup Claude Desktop: Add MCP configuration
Warm up: Run
warm_up_translatortool (first time only)Translate: Use
translate_pdfwith your PDF pathReview: Two files created (dual-language and Chinese-only)
โก Performance
First translation: 2-5 minutes (downloads fonts/models)
Subsequent translations: 30-60 seconds
File size limit: 200MB maximum
Cache size: ~50MB for fonts and models
๐ Troubleshooting
Common Issues
Translation Tool Not Available
The tool automatically installs pdf2zh-next when needed. If issues occur:
# Check status
# Use check_translation_tool in Claude Desktop
# Manual install if needed
pip install pdf2zh-nextFirst Translation Timeout
# Run warmup first
# Use warm_up_translator tool in Claude DesktopPDF File Not Found
Verify file path is correct
Use absolute paths for clarity
Check file hasn't been moved or deleted
Network Issues
Ensure internet connection (required for first-time font downloads)
Check firewall settings
Error Diagnosis
The assistant provides intelligent error diagnosis with specific solutions for:
File not found errors
Invalid PDF files
Translation tool issues
Network connectivity problems
File size limitations
๐ ๏ธ Development
For Developers
Install from source:
git clone https://github.com/huoshuiai/huoshui-pdf-translator.git
cd huoshui-pdf-translator
uv sync
uv run python -m huoshui_pdf_translator.mainBuild and publish:
uv build
uv run twine upload dist/*Project Structure
huoshui-pdf-translator/
โโโ huoshui_pdf_translator/
โ โโโ __init__.py # Package metadata
โ โโโ main.py # FastMCP server implementation
โโโ pyproject.toml # Package configuration
โโโ README.md # This file
โโโ LICENSE # Apache-2.0 license๐ Updates
Update to latest version:
uvx install --upgrade huoshui-pdf-translator
# or
uv tool upgrade huoshui-pdf-translator๐ค Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
๐ License
This project is licensed under the Apache-2.0 License. See the LICENSE file for details.
๐ Acknowledgments
PDFMathTranslate-next: Core translation engine
FastMCP: Framework for intelligent assistant capabilities
Anthropic: MCP protocol and ecosystem
UV & PyPI: Modern Python packaging and distribution
Available Tools
4 toolscheck_translation_toolA
Checks if the PDFMathTranslate-next tool is properly installed and available.
Returns: Dictionary with status information about the translation tool
Inputs: no named parameters. Returns: object
pdf_getA
Retrieves detailed information about a PDF file.
Args: path: PDF file path (absolute or relative to home directory)
Returns: PDF resource with detailed information
Inputs: path (required). Returns: PDF file resource representation
translate_pdfA
Translates a PDF document using PDFMathTranslate-next. Preserves mathematical formulas and layout.
Args: pdf_path: PDF file path (absolute or relative to home directory) output_path: Optional custom output path for the translated PDF
Returns: Dictionary with paths to translated files (dual and mono versions)
Inputs: pdf_path (required), output_path. Returns: object
warm_up_translatorA
Warm up the PDF translator by downloading required assets and models. Run this first to avoid timeouts during actual translation.
Returns: Dictionary with warmup status information
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 4 tools
Each tool has a distinct purpose: pdf_get retrieves PDF info, warm_up_translator prepares the model, translate_pdf performs the translation, and check_translation_tool verifies installation. There is no overlap or ambiguity between them.
Three tools follow a clear verb_noun pattern (warm_up_translator, translate_pdf, check_translation_tool), but pdf_get reverses this to noun_verb, creating a minor inconsistency. The naming is otherwise clear and readable.
With 4 tools, the server is well-scoped for its purpose of PDF translation. Each tool covers a necessary step in the workflow, and the count is appropriate.
The toolset covers the complete workflow: checking installation, warming up models, translating PDFs, and retrieving PDF details. There are no obvious gaps in the provided functionality.
Maintenance
Related MCP Connectors
Translate PDF, scanned PDF, DOCX and EPUB files into 70+ languages with the layout kept.
ๆๆกฃ็ฟป่ฏ๏ผไธไผ DOCX/PDF/PPTX/XLSX/TXT๏ผๆๅฎๅผๆไธ็ฎๆ ่ฏญ่จ๏ผๆฅ่ฏข่ฟๅบฆๅนถไธ่ฝฝๆๅใๆฏๆ ZIP/7Z/RAR ๆน้ๅ ไธๅ่ฏญๅฏน็ งใๆซๆไปถ OCRใ
Translate PDFs and scans into another language in the same layout, every number kept. PDF to Word.
Translate PDFs, scans, Office files and EPUB across 475 languages and styles, preserving layout.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA paper retrieval and content parsing tool based on arXiv, supporting paper search, PDF link retrieval, and content parsing functions, suitable for obtaining the latest papers in academic research and AI fields.2Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that translates scientific PDF documents while preserving original formulas, charts, and layout. It utilizes an OpenAI-compatible backend to provide tools for document translation and language listing.23AGPL 3.0

bluente-translateofficial
AlicenseAqualityCmaintenanceTranslate your documents with formatting intact in 2 minutes69 npm1MIT- AlicenseNot gradedqualityCmaintenanceInteractive PDF workspace shared by a human operator and an AI agent, enabling navigation, search, text extraction, annotations, form filling, and save actions via a PDF.js viewer.MIT