How do I use pdf2zh-next-mcp?

1. Click on "Deploy 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., "@pdf2zh-next-mcp Translate this PDF from English to Korean: /path/to/paper.pdf" 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.

pdf2zh-next-mcp

by JaeHyeon-KAIST

Overview Schema Source Related Servers Discussions Admin

Python

Local

pdf2zh-next-mcp

PyPI License

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

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.

Using Claude Code? Check out pdf2zh-next-skill — a lightweight skill-based approach without MCP overhead. It handles large PDFs better by leveraging Claude Code's direct file I/O and auto-continuation.

How it works

┌─────────────────────────────────────────────────┐
│  Claude Desktop                                  │
│                                                  │
│  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.

Related MCP server: PDF2ZH MCP Server

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

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

Just ask:

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

Behind the scenes:

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

Output files:

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

Limitations

Large PDFs (~30+ pages): Claude Desktop has a per-turn output token limit. For documents with many segments, the translation may fail mid-process with "response could not be fully generated". For large PDFs, use pdf2zh-next-skill with Claude Code instead.
MCP tool result size: Segments are paginated to stay within Claude Desktop's 25K token limit per tool response. This is handled automatically.

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

Available Tools

5 tools

assemble_translatedA

번역된 세그먼트로 최종 PDF를 생성합니다.

백그라운드에서 비동기로 실행됩니다. 반환된 session_dir로 check_assembly_status를 호출하여 완료 여부를 확인하세요.

Args: session_dir: extract_segments에서 반환된 세션 디렉토리 경로 glossary_json: (선택) 용어집 JSON 문자열. 번역 시 생성된 용어집.

ParametersJSON Schema

Name	Required	Description	Default
`session_dir`	Yes
`glossary_json`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/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. It discloses that the tool runs asynchronously in the background and that the caller must check status via check_assembly_status. This is key behavioral context. It does not detail side effects or error modes, but the async disclosure is valuable.

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 efficiently structured: a purpose statement, an async note with follow-up instruction, and a concise args list. Every sentence adds information without redundancy or padding.

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

Completeness4/5

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

The tool is asynchronous with 2 parameters and an output schema. The description covers the async flow, the two parameters, and the follow-up check step. It does not need to explain return values since an output schema exists. Minor missing context: no explicit prerequisite that translated segments must be saved, but that is implied by the workflow.

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?

Schema description coverage is 0%, so the description must compensate. It explains session_dir as the path returned from extract_segments and glossary_json as an optional glossary JSON string created during translation. This adds meaning beyond the bare schema property names and defaults.

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 states 'Creates the final PDF with translated segments' – a clear, specific verb+resource combination. It is distinguished from siblings like check_assembly_status (status check) and extract_segments (extraction) by its unique purpose of assembly.

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

Usage Guidelines4/5

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

The description clearly indicates when to use it: after translating segments, and explicitly instructs to call check_assembly_status with the returned session_dir to monitor completion. It also ties session_dir to extract_segments. While it doesn't explicitly list when not to use it, the workflow context is clear.

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

check_assembly_statusA

PDF 조립 진행 상황을 확인합니다.

assemble_translated 호출 후 이 툴을 호출하여 완료를 확인하세요. 서버가 내부에서 대기 후 응답하므로 별도 대기 불필요합니다.

Args: session_dir: extract_segments에서 반환된 세션 디렉토리 경로

ParametersJSON Schema

Name	Required	Description	Default
`session_dir`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior3/5

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

어노테이션이 없어 설명이 행동 특성을 전달해야 하는데, 서버가 내부 대기 후 응답한다는 점을 명시하여 대기 불필요를 알린다. 그러나 반환 형식이나 오류 조건은 설명하지 않아 일부 정보가 부족하다.

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?

목적, 사용 시점, 인자 설명으로 간결하게 구조화되어 있으며 잉여 정보 없이 모든 문장이 가치를 지닌다.

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?

단순한 툴이고 출력 스키마가 존재하며, 목적·사용 순서·인자 출처가 모두 포함되어 충분히 완결적이다.

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?

스키마 설명 커버리지가 0%이지만, session_dir이 extract_segments에서 반환된 경로임을 명시하여 스키마 이상의 의미를 제공한다. 단일 파라미터에 대해 충분히 설명한다.

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?

명확한 동사+리소스 'PDF 조립 진행 상황 확인'으로 시작하며, assemble_translated 후 호출하라는 순서까지 제시되어 형제 툴인 check_extraction_status와 차별화된다.

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

Usage Guidelines4/5

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

assemble_translated 호출 후 이 툴을 호출하라는 명시적 지침과 서버가 내부 대기 후 응답하므로 별도 대기가 필요 없다는 맥락이 포함되어 있다. 다만 대안이나 배제 조건은 없다.

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

check_extraction_statusA

세그먼트 추출 진행 상황을 확인합니다.

extract_segments 호출 후 이 툴을 호출하여 완료를 확인하세요. 서버가 내부에서 대기 후 응답하므로 별도 대기 불필요합니다. 완료되면 세그먼트와 번역 instruction을 반환합니다.

Args: session_dir: extract_segments에서 반환된 세션 디렉토리 경로 offset: 세그먼트 시작 인덱스 (기본값: 0). 세그먼트가 많을 때 나눠서 가져올 수 있습니다.

ParametersJSON Schema

Name	Required	Description	Default
`offset`	No
`session_dir`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

With no annotations provided, the description carries the burden of behavioral disclosure. It discloses the internal waiting behavior, return content, and supports chunked fetching. Lacks details about error handling or idempotency, but the core behavior is well described.

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 well-structured with purpose, usage note, return info, and parameter explanations. It is slightly repetitive (mentions extract_segments twice) but remains tight and front-loaded.

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?

For a status-check tool in a pipeline, the description covers the essential context: trigger (previous tool), behavior (server waits), return value (segments + instructions), and pagination. Sibling tool names reinforce the pipeline context.

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

Parameters5/5

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

Schema coverage is 0%, so the description fully compensates by explaining session_dir as the path returned from extract_segments and offset as the start index for pagination. This exceeds the schema's bare definitions.

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 'Check segment extraction progress' and explains that it returns segments and translation instructions when complete. It explicitly references the preceding tool extract_segments, distinguishing it from other pipeline steps like check_assembly_status.

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

Usage Guidelines5/5

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

Provides explicit when-to-use guidance: call after extract_segments to confirm completion. Also notes that no separate wait is needed because the server waits internally, and mentions the offset parameter for pagination when segments are numerous.

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

extract_segmentsA

PDF 파일에서 번역 대상 세그먼트를 추출합니다.

백그라운드에서 비동기로 실행됩니다. 반환된 session_dir로 check_extraction_status를 호출하여 완료 여부를 확인하세요.

Args: file: PDF 파일의 로컬 절대 경로. 예: /Users/username/Downloads/paper.pdf 주의: 반드시 사용자가 메시지에 입력한 로컬 경로를 사용하세요. 첨부 파일의 내부 경로(/mnt/user-data/uploads/...)는 사용할 수 없습니다. lang_in: 원본 언어 코드 (기본값: en) lang_out: 번역 대상 언어 코드 (기본값: ko) output_dir: 출력 디렉토리 경로. 비어 있으면 입력 PDF와 같은 디렉토리에 저장. pages: 번역할 페이지 범위. 비어 있으면 전체 페이지. 형식: '1-7,10' (1~~7, 10페이지), '-5' (1~~5), '3-' (3~끝). 참고문헌 등 특정 페이지를 제외하고 싶을 때 사용하세요.

ParametersJSON Schema

Name	Required	Default
`file`	Yes
`pages`	No
`lang_in`	No	en
`lang_out`	No	ko
`output_dir`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden. It discloses the asynchronous behavior, the returned session_dir, default parameter values, and page-range syntax. It does not cover error conditions or side effects on existing files, but it covers the main behavioral traits comprehensively.

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 well-structured with an intro, async note, and a clear Args list. It is slightly verbose due to the path warning and examples, but each sentence contributes necessary information.

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

Completeness4/5

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

Given the tool's complexity (async, five parameters, output schema), the description covers the essential invocation requirements: what to pass, the async flow with session_dir, and next-step status checking. It omits error handling, but is sufficient for correct tool selection and invocation.

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

Parameters5/5

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

The input schema has zero descriptions, but the description fully compensates by detailing every parameter: file with a path example and restriction, lang_in/lang_out with defaults, output_dir behavior, and pages with format examples ('1-7,10', '-5', '3-'). This adds significant meaning beyond the raw schema.

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 it 'extracts segments to be translated from a PDF file' and differentiates itself by noting the asynchronous execution and the need to call check_extraction_status for completion. This makes it distinct from sibling tools like save_translated_segments or assemble_translated.

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

Usage Guidelines4/5

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

It provides explicit guidance to call check_extraction_status after obtaining session_dir, and includes a critical warning about using local file paths instead of attached internal paths. It does not mention exclusions or alternatives explicitly, but the pipeline context is clear enough.

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

save_translated_segmentsA

번역된 세그먼트를 세션에 저장합니다.

여러 번 호출하면 기존 세그먼트에 누적됩니다. 모든 세그먼트 저장 후 assemble_translated를 호출하세요.

Args: session_dir: extract_segments에서 반환된 세션 디렉토리 경로 segments_json: 번역된 세그먼트 JSON 배열 문자열

ParametersJSON Schema

Name	Required	Description	Default
`session_dir`	Yes
`segments_json`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses the accumulation behavior across calls, which is important. However, it does not mention error handling, validation, or what happens if session_dir is invalid, leaving some behavioral gaps.

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 concise and well-structured: main purpose, accumulation behavior, sequencing instruction, then a clear Args list. Every sentence earns its place without redundancy.

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

Completeness4/5

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

With an output schema present, return values need not be described. The description covers purpose, parameter origins, and workflow sequencing within the sibling tool context. It lacks edge-case behavior, but is complete for the primary use case.

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?

Schema description coverage is 0%, so the description compensates by explaining both parameters: session_dir as the path from extract_segments and segments_json as a JSON array string of translated segments. This adds meaning beyond bare names, though format details are not deeply specified.

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 purpose: 'Saves translated segments to the session' with a specific verb and resource. It also distinguishes itself from siblings by describing the accumulation behavior and the call to assemble_translated.

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

Usage Guidelines5/5

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

The description provides explicit usage guidance: segments accumulate across multiple calls, and assemble_translated should be called after all segments are saved. It also explains that session_dir comes from extract_segments, giving a clear workflow context.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv0.2.1Aug 1, 2026
- First observedassemble_translated
- First observedcheck_assembly_status
- First observedcheck_extraction_status
- First observedextract_segments
- First observedsave_translated_segments

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored 2026-08-01 07:50 across 5 tools

Disambiguation5/5

Each tool targets a distinct stage of the PDF translation pipeline: extraction initiation, extraction status, saving translations, assembly initiation, and assembly status. Even the two status-checking tools are clearly differentiated by their target phase (extraction vs assembly), making misselection unlikely.

Naming Consistency5/5

All tool names follow a predictable verb_noun pattern (extract_, check_, save_, assemble_). The nouns clearly indicate the resource or phase (segments, extraction_status, translated_segments, translated, assembly_status), providing a consistent and intuitive naming convention.

Tool Count5/5

With 5 tools, the set is well-scoped for the intended workflow. Each tool represents a necessary step in the asynchronous extraction-translation-assembly pipeline, and none are redundant or extraneous.

Completeness5/5

The tool set covers the complete lifecycle of the PDF translation process: initiate extraction, monitor/retrieve results, save translations, initiate assembly, and monitor/retrieve the final output. There are no obvious dead ends or missing operations required to complete the core workflow.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

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
PDF Redaction MCP AOAuth
com.pdf-redaction
MCP server for detecting and redacting PII (Personally Identifiable Information) in PDF documents.
File Systems Security
23
Translation Services Mcp A
io.github.varvararatta
MCP server for Translation Services
Language Translation AI & Machine Learning
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

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
PDF2ZH MCP Server
Language Translation Documentation Access Research & Data
lichman0405
A
license
A
quality
D
maintenance
An 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.
Updated 7 months ago (2026-02-28 04:02 UTC)
2
3
AGPL 3.0
pdf-mcp
Documentation Access File Systems Research & Data
I-CAN-hack
A
license
A
quality
C
maintenance
An MCP server for reading, rendering, and searching PDF files, specifically optimized for LLMs to extract text, tables, and technical diagrams. It enables metadata retrieval, multi-format text extraction, and page-to-image rendering using PyMuPDF.
Updated a month ago (2026-07-30 09:07 UTC)
5
77
MIT
pymupdf4llm-mcpofficial
File Systems
pymupdf
A
license
Not graded
quality
B
maintenance
MCP server for exporting PDF to markdown, optimized for LLM consumption.
Updated 2 months ago (2026-07-02 13:12 UTC)
1,982 PyPI
72
AGPL 3.0

pdf2zh-next-mcp

How it works

Prerequisites

Installation

From PyPI (recommended)

From GitHub

From source

Setup

Usage

Limitations

Troubleshooting

BabeldocError: cannot unpack non-iterable NoneType object

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

pymupdf4llm-mcpofficial

`BabeldocError: cannot unpack non-iterable NoneType object`