pdf-translate MCP

Local MCP server for Claude Desktop that runs the full pdf-translate pipeline:

extract.py → parallel API translation → check.py → apply.py

Install

cd D:\Internship\skill\pdf-translate-mcp
pip install -r requirements.txt

Parent scripts (extract.py, check.py, apply.py) live in D:\Internship\skill\ and are called automatically.

Claude Desktop config

Edit %APPDATA%\Claude\claude_desktop_config.json — merge into existing mcpServers:

"pdf-translate": {
  "command": "C:\\Users\\neelima\\Anaconda3\\python.exe",
  "args": ["D:\\Internship\\skill\\pdf-translate-mcp\\server.py"],
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-YOUR_KEY_HERE"
  }
}

Fully quit Claude Desktop (tray → Exit), reopen, start a new chat.

Tools

Tool	When to use
start_translate_pdf_job	Recommended for 50-page PDFs. Returns job_id in <1s; poll with get_translate_pdf_job.
get_translate_pdf_job	Poll every 15–30s until status is done or failed.
translate_pdf_path	Small/fast one-shot jobs only (Desktop kills tools after ~4 min).
translate_pdf_base64	Tiny PDFs only (~<750KB raw).

Example prompt (job-based — use this for 50 pages)

Call start_translate_pdf_job on C:\Users\neelima\Downloads\50_pages_french.pdf with target_lang en and output_path C:\Users\neelima\Downloads\50_pages_french_en.pdf. Poll get_translate_pdf_job every 20 seconds until done. Report stats.timing_s and wall-clock time.

Example prompt (blocking path — small PDFs only)

Call translate_pdf_path on C:\Users\neelima\Downloads\small.pdf with target_lang en.

Base64 limit

Do not use translate_pdf_base64 for multi-page PDFs in Desktop. read_media_file and tool results are capped at 1MB; a 1.09 MB PDF becomes ~1.5M chars of base64 and fails before translation starts.

Local test (no Claude)

# Extract only (no API key)
python tests\test_pipeline_local.py --extract-only "C:\Users\neelima\Downloads\50_pages_french.pdf"

# Full pipeline (needs ANTHROPIC_API_KEY)
$env:ANTHROPIC_API_KEY = "sk-ant-..."
python tests\test_pipeline_local.py "C:\Users\neelima\Downloads\50_pages_french.pdf" -t en

Job artifacts: pdf-translate-mcp/runs/<job_id>/

Timing (typical 50-page doc)

Stage	~seconds
extract	2–5
translate	45–60
check	<1
apply	35–45
total	~85–110

Troubleshooting

“Linux cloud VM” / paths not reachable / no translate_pdf_path

You are almost certainly in Cowork mode, not a local MCP chat.

Mode	Where it runs	translate_pdf_path	C:\Users\... paths
Regular Desktop chat	Your PC	Yes (if MCP connected)	Yes
Cowork	Remote Linux VM	No	No

Fix: In Claude Desktop, start a normal new chat (not Cowork). Cowork uses the pdf-translate skill in a VM; your MCP server only works in regular chat.

pdf-translate tools not listed

1. Quit Desktop fully (tray → Exit) after editing claude_desktop_config.json.
2. Reopen → new regular chat.
3. Check logs: %APPDATA%\Claude\logs\ for mcp-server-pdf-translate.log or [pdf-translate] in mcp.log.
4. If only filesystem appears in logs, Desktop never started pdf-translate — fix JSON syntax or Python path.

Server not listed

• Connection error: Run python server.py manually — should hang waiting on stdin (that’s normal).
• ANTHROPIC_API_KEY: Must be in the env block of Desktop config.

4-minute timeout

Claude Desktop hard-kills any MCP tool call after ~4 minutes, even if the server is still working. Your 08:52 run proves this: the server was still translating when Desktop cancelled.

Use start_translate_pdf_job + get_translate_pdf_job for 50-page PDFs. The start call returns in under a second; poll until status is done.

If the MCP log shows asyncio.run() cannot be called from a running event loop, restart Claude Desktop after updating the server.

Large base64 fails

Use translate_pdf_path instead. Desktop caps tool payloads at ~1MB.

See PLAN.md for architecture notes.