pdf2zh-next-mcp 0.1.1

MCP server for PDF translation via pdf2zh-next with full-context LLM translation

pdf2zh-next-mcp

MCP server for PDF translation using pdf2zh-next as the PDF processing backend.

Instead of translating each segment independently (which loses context), this server extracts all segments at once and lets the LLM translate them together — preserving terminology consistency and context across the entire document.

How it works

┌─────────────────────────────────────────────────┐
│  MCP Client (Claude Desktop, Claude Code, etc.) │
│                                                  │
│  1. extract_segments  ──→  segments + formulas   │
│  2. LLM translates all segments at once          │
│  3. assemble_translated  ──→  final PDF          │
└─────────────────────────────────────────────────┘

The LLM sees every segment before translating — so terminology stays consistent, cross-page sentences flow naturally, and formula placeholders are preserved correctly.

Prerequisites

pdf2zh-next must be installed separately:

uv tool install pdf2zh-next

Verify installation:

pdf2zh_next --version

You need uv to install both pdf2zh-next and this server.

Installation

From PyPI (recommended)

uv tool install pdf2zh-next-mcp

From GitHub

uv tool install git+https://github.com/JaeHyeon-KAIST/pdf2zh-next-mcp

From source

git clone https://github.com/JaeHyeon-KAIST/pdf2zh-next-mcp
cd pdf2zh-next-mcp
uv sync

Setup

Claude Code

claude mcp add pdf-translate -- pdf2zh-next-mcp

Claude Desktop

Add to your Claude Desktop MCP config:

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

If installed from PyPI or GitHub:

{
  "mcpServers": {
    "pdf-translate": {
      "command": "uvx",
      "args": ["pdf2zh-next-mcp"]
    }
  }
}

If running from source:

{
  "mcpServers": {
    "pdf-translate": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/pdf2zh-next-mcp",
        "python", "-m", "pdf2zh_next_mcp.main"
      ]
    }
  }
}

Tip: If Claude Desktop can't find uvx, use the absolute path (e.g., /opt/homebrew/bin/uvx on macOS, C:\Users\you\.local\bin\uvx.exe on Windows).

Usage

Basic mode (default)

Text-only translation. The LLM reads all segments first, identifies key terms, then translates with consistent terminology.

Just ask:

"Translate this PDF to Korean: /path/to/paper.pdf"

Behind the scenes:

1. extract_segments analyzes the PDF layout and returns all text segments
2. The LLM translates everything at once (with full context)
3. assemble_translated injects translations and generates the final PDF

Visual mode

Uses the attached PDF for visual context — the LLM can see figures, tables, and formulas. Also saves a terminology glossary.

1. Attach the PDF to the chat (drag-and-drop)
2. Ask: "Translate this PDF to Korean in visual mode"
3. The LLM creates a glossary, references the visuals, and translates all segments

Visual mode outputs:

• *-mono.pdf — translated PDF
• *-dual.pdf — bilingual side-by-side
• *-glossary.json — terminology glossary

Troubleshooting

BabeldocError: cannot unpack non-iterable NoneType object

BabelDOC needs CMap files for font character mapping. If its automatic download times out, install them manually:

cd ~/Downloads
curl -L https://github.com/funstory-ai/BabelDOC-Assets/archive/refs/heads/main.zip -o BabelDOC-Assets.zip
unzip BabelDOC-Assets.zip
mkdir -p ~/.cache/babeldoc/cmap
cp BabelDOC-Assets-main/cmap/*.json ~/.cache/babeldoc/cmap/

This is a one-time setup. The cache path is the same on all platforms.

License

MIT