pdf-toolbox-mcp

Servicio MCP de procesamiento de PDF con prioridad local: OCR con escritura inversa, desbloqueo, renderizado, división/combinación, redacción y compresión, todo realizado localmente.

GitHub

Prueba este MCPPatrocinado

Documentación

pdf-toolbox-mcp

中文文档 | Procesamiento local de PDF para agentes de IA.

Diseñado para personas que ya usan Claude Desktop, Claude Code, Cursor u otro cliente MCP y que quieren OCR local de PDF, desbloqueo, dividir/combinar, renderizar y comprimir sin subir archivos.

Otros ayudan a la IA a leer PDFs. Este la ayuda a procesarlos — convierte un escaneo en un archivo realmente buscable con OCR, desbloquea PDFs cifrados, divide/combina/rota, y vuelve a cifrar para compartir. 100% en tu máquina: sin llamadas a la nube, sin subidas de archivos, sin tarifas por página.

Inicio rápido

Añádelo a cualquier cliente MCP:

{
  "mcpServers": {
    "pdf-toolbox": {
      "command": "uvx",
      "args": ["--from", "pdf-toolbox-mcp", "pdftoolbox"]
    }
  }
}

Página del proyecto en PyPI: pdf-toolbox-mcp

¿Necesitas una configuración lista para pegar para un cliente específico?

Listar clientes: uv run pdftoolbox client list
Claude Desktop: uv run pdftoolbox client show claude-desktop
Cursor: uv run pdftoolbox client show cursor
Proyecto universal .mcp.json: uv run pdftoolbox client show universal
Exportar todos los archivos de cliente: uv run pdftoolbox client export
Detectar la superficie del cliente actual: uv run pdftoolbox client detect
Instalación semiautomática: uv run pdftoolbox client install o uv run pdftoolbox client install --scope auto
Importar una configuración existente de Claude Desktop a Claude Code: uv run pdftoolbox client import-claude-desktop
Añade --all solo si quieres todos los paquetes de clientes compatibles

¿Necesitas un diagnóstico único y una instantánea de dependencias antes de tu primera tarea? Ejecuta uv run pdftoolbox doctor o uv run pdftoolbox doctor --json. Imprime available_now, starter_action, starter_cli y starter_tool para que puedas ir directo a la primera acción compatible.

Primera tarea:

OCR de un escaneo: uv run pdftoolbox ocr scan.pdf --lang chi_sim+eng
Desbloquear un archivo: uv run pdftoolbox unlock locked.pdf --password 'xxx'

Primera tarea MCP:

Pregunta a tool_doctor
Luego llama a tool_ocr_pdf

Las dependencias de Python se resuelven automáticamente. Las herramientas del sistema están niveladas por capacidad — las que faltan nunca bloquean el servidor; la herramienta devuelve un error estructurado con el comando de instalación exacto:

¿Necesitas toda la pila de una vez?

macOS: brew install qpdf poppler tesseract tesseract-lang ghostscript
Debian/Ubuntu: sudo apt install qpdf poppler-utils tesseract-ocr tesseract-ocr-chi-sim ghostscript
Windows: usa los comandos por paquete en la tabla siguiente

Nivel	Binario	Desbloquea	macOS	Debian/Ubuntu	Windows
L0	qpdf	dividir / combinar / rotar / desbloquear	`brew install qpdf`	`apt install qpdf`	`choco/scoop install qpdf`
L1	poppler	extract_text / render / info	`brew install poppler`	`apt install poppler-utils`	`choco/scoop install poppler` o conda-forge
L2	tesseract	ocr_pdf (escritura)	`brew install tesseract tesseract-lang`	`apt install tesseract-ocr tesseract-ocr-chi-sim`	`choco/scoop install tesseract`
L3	ghostscript	comprimir	`brew install ghostscript`	`apt install ghostscript`	`scoop install ghostscript` / `winget install ArtifexSoftware.GhostScript`

Nota para Windows: el binario de Ghostscript es gswin64c.exe allí — la sonda lo detecta automáticamente, así que compress_pdf funciona sin configuración adicional. Los paquetes de idioma de Tesseract (p. ej. chi_sim) deben descargarse por separado a su carpeta tessdata.

Referencias / aguas arriba:

qpdf: sitio web · repositorio
poppler: sitio web
tesseract: repositorio
ghostscript: sitio web · lanzamientos

Cada respuesta exitosa incluye un resumen _deps ({"level": 2, "missing": ["gs"]}) para que el agente siempre sepa qué está disponible.

En una sesión MCP, usa tool_doctor.

¿Por qué otro MCP de PDF?

El espacio de MCP de PDF está saturado — pero solo en el lado de la lectura. Basado en una encuesta práctica del ecosistema (2026-09):

Capacidad	pdf-toolbox	Citra (916★)	ODA PDF-Tools (153★)	jztan/pdf-mcp (130★)	MCPs SaaS en la nube
Escritura OCR → archivo PDF buscable	✅	❌ solo lectura	❌ (sin OCR)	❌ solo lectura	☁️ de pago
Desbloquear cifrado (contraseña de usuario)	✅	❌ fallo duro	⚠️ solo contraseña de propietario	❌ fallo duro	☁️ de pago
Dividir / combinar / rotar	✅	❌	✅	❌	☁️ de pago
Comprimir hasta un tamaño objetivo	✅	❌	❌	❌	☁️ de pago
Renderizar páginas para visión	✅	✅	✅	✅	☁️
100% local y privado	✅	✅	✅	✅	❌

Puntos débiles que aborda directamente:

Claude rechaza de forma nativa los PDFs cifrados; ChatGPT informa "No se pudo extraer texto" en escaneos — aquí, el OCR escribe una capa de texto real de vuelta al archivo, y unlock_pdf descifra solo con la contraseña de usuario (enviada a qpdf por stdin, nunca expuesta en argumentos de proceso).
Claude Code consume ~30× más tokens al leer una página de PDF como imagen que al extraer texto localmente.

Herramientas (25)

Herramienta	Qué hace	Motor
`pdf_info`	Páginas, estado de cifrado, metadatos — llámala siempre primero	pdfinfo
`is_searchable`	Enrutamiento inteligente: verificación de densidad de texto → recomienda `extract_text` o `ocr_pdf`	pdftotext
`extract_text`	Texto con conciencia de diseño, rangos de página exactos `1-3,5`, modo por página	pdftotext
`ocr_pdf`	Escritura OCR: escaneo → PDF buscable (enderezado, omitir/rehacer, respaldo de idioma)	OCRmyPDF
`batch_ocr`	OCR de directorio completo con resultados por archivo, reintentos, tiempos de espera	OCRmyPDF
`render_pages`	PNG por página, `return_images=true` transmite bloques de imagen al modelo de visión	pdftoppm
`extract_images`	Extraer imágenes incrustadas (inventario o archivos PNG)	pdfimages
`extract_attachments`	Extraer archivos adjuntos incrustados	pdfdetach
`list_fonts`	Auditoría de fuentes — las fuentes no incrustadas pueden perder glifos en otras máquinas	pdffonts
`unlock_pdf`	Descifrar con contraseña de usuario, genera un archivo descifrado limpio; la contraseña se envía por stdin	qpdf
`protect_pdf`	AES-256 + permisos granulares (imprimir/extraer/modificar/…)	pikepdf
`split_pdf`	Por rangos o cada N páginas	qpdf
`merge_pdfs`	Combinación ordenada	qpdf
`rotate_pages`	90/180/270 en páginas seleccionadas	qpdf
`check_repair`	Verificación estructural; `repair=true` reconstruye archivos dañados	qpdf
`linearize`	Salida optimizada para web con carga progresiva	qpdf
`sanitize`	Higiene de publicación: elimina JS/OpenAction/metadatos/adjuntos	pikepdf
`redact`	Redacción real: las páginas afectadas se rasterizan + cajas opacas — el texto redactado es físicamente irrecuperable, otras páginas conservan su capa de texto (`rasterize_all=true` para máxima protección)	pdftoppm + PIL
`redact_text`	Redactar por contenido: localiza cada aparición de las palabras clave y las tacha — sin necesidad de coordenadas manuales	pdftotext -bbox
`locate_text`	Encuentra dónde aparece el texto: página + cajas delimitadoras (puntos PDF, origen arriba-izquierda) — la base para redacción y resaltado	pdftotext -bbox
`fill_form`	Rellenar campos AcroForm (los campos faltantes se informan)	pikepdf
`edit_metadata`	Establecer/limpiar Título/Autor/… (docinfo + XMP)	pikepdf
`compress_pdf`	Comprimir, opcionalmente bajando una escalera de calidad hasta alcanzar `target_mb`	ghostscript
`dependency_status`	Sondear herramientas del sistema + comandos de instalación	—
`doctor`	Verificación de incorporación en un solo paso: importaciones, sonda de dependencias, rutas del README	—

Contrato de errores (los agentes se autoenrutan): los fallos devuelven {"ok": false, "error": "<code>"} — missing_dependency (con install por plataforma), encrypted_pdf (pista: llama a unlock_pdf primero), wrong_password, output_exists (se requiere sobrescritura explícita), invalid_page_range, …

Seguridad de salida

Las salidas de un solo archivo se escriben en un archivo temporal del mismo directorio y se reemplazan atómicamente solo después de que la operación tenga éxito.
render_pages, extract_images y extract_attachments preparan exportaciones de varios archivos en un directorio temporal y las publican solo cuando todos los archivos están listos.
overwrite tiene como valor predeterminado false; pasa overwrite=true (o el CLI --overwrite) para reemplazar una salida existente. Los intentos fallidos dejan la salida anterior intacta.
Las contraseñas de desbloqueo se pasan a qpdf por stdin, y las contraseñas de protección permanecen dentro del proceso Python/pikepdf en lugar de en argumentos de línea de comandos.

Ejemplos

En un cliente MCP, solo describe el resultado — el agente encadena las herramientas por sí mismo, y el contrato de errores lo hace autoenrutable (un error encrypted_pdf le indica que llame a unlock_pdf primero, y así sucesivamente). Para uso sin interfaz, define una vez:

PTX="uvx --from pdf-toolbox-mcp pdftoolbox"
# PyPI form: uvx --from pdf-toolbox-mcp pdftoolbox

1 · Escaneo → PDF buscable (el buque insignia)

“contract-scan.pdf es un contrato escaneado que no puedo buscar. Hazlo buscable — mayormente chino con algo de inglés.”

Agente: pdf_info → is_searchable informa baja densidad de texto → ocr_pdf(path, lang="chi_sim+eng") escribe contract-scan_ocr.pdf. La extracción de texto y Ctrl+F ahora funcionan en la salida.

$PTX ocr contract-scan.pdf --lang chi_sim+eng
$PTX text contract-scan_ocr.pdf --pages 1-3

2 · PDF cifrado → legible

“locked.pdf está protegido con contraseña; la contraseña es hunter2. Desbloquéalo y resume la página 3.”

Agente: unlock_pdf(path, password="hunter2") → locked_unlocked.pdf → extract_text(pages="3").

$PTX unlock locked.pdf --password 'hunter2'
$PTX text locked_unlocked.pdf --pages 3

3 · Redactar secretos antes de compartir

“Tacha cada aparición de 张三 y HT-2026-088 en draft.pdf — debe ser físicamente irrecuperable.”

Agente: redact_text(queries=["张三", "HT-2026-088"]) → draft_redacted.pdf. Las páginas con coincidencias se rasterizan, así que las cadenas desaparecen de los píxeles y de la capa de texto; otras páginas conservan su texto seleccionable. Verifica ejecutando extract_text en la salida: se esperan cero coincidencias.

$PTX redact-text draft.pdf --query 张三 --query HT-2026-088

Más recetas — combinar y proteger, comprimir hasta un objetivo, OCR por lotes, la cadena de higiene de publicación (sanitize → edit_metadata → linearize), renderizado para visión, localizar y redactar, relleno de formularios, rescate de archivos dañados — en el recetario.

Configuración

Env	Predeterminado	Significado
`PDF_TOOLBOX_TESS_LANG`	`chi_sim+eng`	Idiomas OCR predeterminados; los paquetes faltantes se degradan automáticamente (señalado vía `lang_fallback`)
`PDF_TOOLBOX_WORKSPACE`	sin establecer	Si se establece, todas las escrituras se limitan a este directorio; los directorios del sistema siempre se deniegan

CLI

Todo también está disponible sin interfaz (ideal para scripts y CI):

uvx --from pdf-toolbox-mcp pdftoolbox ocr scan.pdf --lang chi_sim+eng
uvx --from pdf-toolbox-mcp pdftoolbox unlock locked.pdf --password 'xxx'
uvx --from pdf-toolbox-mcp pdftoolbox split big.pdf --every-n 10
uvx --from pdf-toolbox-mcp pdftoolbox probe all

(Usa uvx --from pdf-toolbox-mcp … al instalar desde PyPI.)

Seguridad y privacidad

Sin llamadas de red. Los archivos nunca salen de la máquina.
Todas las llamadas a subprocesos usan listas de argumentos (sin interpolación de shell); el análisis de rangos de página es compartido y validado.
Las salidas nunca se sobrescriben silenciosamente: overwrite=true debe pasarse explícitamente.
Las escrituras respetan PDF_TOOLBOX_WORKSPACE; los directorios del sistema se deniegan, y las salidas preparadas se publican atómicamente.
Las contraseñas nunca se registran en los payloads de error.
El contenido de PDF no confiable se señala en las descripciones de las herramientas (conciencia de inyección de prompts).

Cumplimiento de licencia

MIT. Las herramientas del sistema se invocan como procesos independientes (agregación): poppler (GPL-2.0), qpdf (Apache-2.0), tesseract (Apache-2.0), ghostscript (AGPL, opcional); las dependencias de Python ocrmypdf/pikepdf son MPL-2.0. Consulta PLAN.md §7 para la tabla completa.

Desarrollo

uv sync --dev          # install
uv run pytest -m "not realworld"  # fast path
uv run pytest -m realworld        # noisy / slower regression pack
uv run pytest                     # full suite
uv run pdftoolbox probe all
uv run pdftoolbox probe all --json   # structured dependency snapshot
uv run pdftoolbox doctor
uv run python tools/onboarding_check.py
uv run python tools/onboarding_check.py --json

Verificación multiplataforma sin salir de macOS:

docker run --rm -v "$PWD":/src:ro python:3.12-slim bash -c \
  'apt-get update -qq >/dev/null && apt-get install -y -qq poppler-utils tesseract-ocr qpdf ghostscript >/dev/null &&
   pip install -q uv && cp -r /src /work && cd /work && uv sync --dev --quiet && uv run pytest -q'

Hoja de ruta: v0.1.4 incluye las 25 herramientas anteriores; v0.1.5 endureció la seguridad de salida y el aislamiento de fallos; v0.1.6 endurece el manejo de secretos, las escrituras de configuración y la extracción de páginas dispersas. No-objetivos explícitos: editar texto existente, descifrar contraseñas — consulta PLAN.md.

Licencia

MIT