pdf-toolbox-mcp

pdf-toolbox-mcp

中文文档 | Processamento local de PDFs para agentes de IA.

Feito para quem já usa Claude Desktop, Claude Code, Cursor ou outro cliente MCP e quer OCR local de PDF, desbloqueio, divisão/combinação, renderização e compressão sem enviar arquivos.

Outros ajudam a IA a ler PDFs. Este ajuda a IA a processá-los — faça OCR de uma digitalização em um arquivo realmente pesquisável, desbloqueie PDFs criptografados, divida/combine/gire, re-criptografe para compartilhar. 100% na sua máquina: sem chamadas em nuvem, sem uploads de arquivos, sem taxas por página.

Início rápido

Adicione a qualquer cliente MCP:

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

Página do projeto no PyPI: pdf-toolbox-mcp

Precisa de uma configuração pronta para colar em um 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
• Projeto universal .mcp.json: uv run pdftoolbox client show universal
• Exportar todos os arquivos de clientes: uv run pdftoolbox client export
• Detectar a superfície do cliente atual: uv run pdftoolbox client detect
• Instalação semiautomática: uv run pdftoolbox client install ou uv run pdftoolbox client install --scope auto
• Importar uma configuração existente do Claude Desktop para o Claude Code: uv run pdftoolbox client import-claude-desktop
• Adicione --all apenas se quiser todos os pacotes de clientes suportados

Precisa de um diagnóstico único e um instantâneo de dependências antes da sua primeira tarefa? Execute uv run pdftoolbox doctor ou uv run pdftoolbox doctor --json. Ele imprime available_now, starter_action, starter_cli e starter_tool para que você possa ir direto para a primeira ação suportada.

Primeira tarefa:

• OCR de uma digitalização: uv run pdftoolbox ocr scan.pdf --lang chi_sim+eng
• Desbloquear um arquivo: uv run pdftoolbox unlock locked.pdf --password 'xxx'

Primeira tarefa MCP:

1. Pergunte a tool_doctor
2. Em seguida, chame tool_ocr_pdf

As dependências Python são resolvidas automaticamente. As ferramentas do sistema são niveladas por capacidade — as ausentes nunca travam o servidor; a ferramenta retorna um erro estruturado com o comando de instalação exato:

Precisa de toda a pilha de uma 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: use os comandos por pacote na tabela abaixo

Nível	Binário	Desbloqueia	macOS	Debian/Ubuntu	Windows
L0	qpdf	dividir / combinar / girar / 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 ou conda-forge
L2	tesseract	ocr_pdf (gravação de volta)	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: o binário do Ghostscript é gswin64c.exe lá — a sondagem o detecta automaticamente, então compress_pdf funciona de imediato. Os pacotes de idioma do Tesseract (por exemplo, chi_sim) devem ser baixados para a pasta tessdata separadamente.

Referência / upstream:

• qpdf: site · repositório
• poppler: site
• tesseract: repositório
• ghostscript: site · versões

Toda resposta bem-sucedida traz um resumo _deps ({"level": 2, "missing": ["gs"]}) para que o agente sempre saiba o que está disponível.

Em uma sessão MCP, use tool_doctor.

Por que outro MCP de PDF?

O espaço de MCPs de PDF está lotado — mas apenas no lado da leitura. Com base em uma pesquisa prática do ecossistema (2026-09):

Capacidade	pdf-toolbox	Citra (916★)	ODA PDF-Tools (153★)	jztan/pdf-mcp (130★)	MCPs SaaS em nuvem
Gravação de OCR → arquivo PDF pesquisável	✅	❌ somente leitura	❌ (sem OCR)	❌ somente leitura	☁️ pago
Desbloquear criptografado (senha de usuário)	✅	❌ falha total	⚠️ somente senha de proprietário	❌ falha total	☁️ pago
Dividir / combinar / girar	✅	❌	✅	❌	☁️ pago
Comprimir até o tamanho desejado	✅	❌	❌	❌	☁️ pago
Renderizar páginas para visão	✅	✅	✅	✅	☁️
100% local e privado	✅	✅	✅	✅	❌

Pontos problemáticos que isso resolve diretamente:

• O Claude nativamente recusa PDFs criptografados; o ChatGPT relata "Nenhum texto pôde ser extraído" em digitalizações — aqui, o OCR grava uma camada de texto real de volta no arquivo, e unlock_pdf descriptografa apenas com a senha do usuário (enviada ao qpdf via stdin, nunca exposta nos argumentos do processo).
• O Claude Code gasta ~30× mais tokens lendo uma página de PDF como imagem do que extraindo texto localmente.

Ferramentas (25)

Ferramenta	O que faz	Mecanismo
pdf_info	Páginas, status de criptografia, metadados — sempre chame primeiro	pdfinfo
is_searchable	Roteamento inteligente: verificação de densidade de texto → recomenda extract_text ou ocr_pdf	pdftotext
extract_text	Texto com consciência de layout, intervalos exatos de páginas 1-3,5, modo por página	pdftotext
ocr_pdf	Gravação de OCR: digitalização → PDF pesquisável (correção de inclinação, pular/refazer, fallback de idioma)	OCRmyPDF
batch_ocr	OCR de diretório inteiro com resultados por arquivo, tentativas, tempos limite	OCRmyPDF
render_pages	PNG por página, return_images=true transmite blocos de imagem para o modelo de visão	pdftoppm
extract_images	Extrair imagens incorporadas (inventário ou arquivos PNG)	pdfimages
extract_attachments	Extrair arquivos de anexos incorporados	pdfdetach
list_fonts	Auditoria de fontes — fontes não incorporadas podem perder glifos em outras máquinas	pdffonts
unlock_pdf	Descriptografar com senha de usuário, gerar um arquivo descriptografado limpo; senha enviada via stdin	qpdf
protect_pdf	AES-256 + permissões granulares (imprimir/extrair/modificar/…)	pikepdf
split_pdf	Por intervalos ou a cada N páginas	qpdf
merge_pdfs	Combinação ordenada	qpdf
rotate_pages	90/180/270 em páginas selecionadas	qpdf
check_repair	Verificação estrutural; repair=true reconstrói arquivos danificados	qpdf
linearize	Saída otimizada para web com carregamento progressivo	qpdf
sanitize	Higiene de publicação: remover JS/OpenAction/metadados/anexos	pikepdf
redact	Redação verdadeira: páginas afetadas rasterizadas + caixas opacas — texto redigido fisicamente irrecuperável, outras páginas mantêm a camada de texto (rasterize_all=true para proteção máxima)	pdftoppm + PIL
redact_text	Redigir por conteúdo: localizar cada ocorrência das palavras-chave e apagá-las — sem coordenadas manuais	pdftotext -bbox
locate_text	Encontrar onde o texto ocorre: página + caixas delimitadoras (pontos PDF, origem no canto superior esquerdo) — a base para redação e destaque	pdftotext -bbox
fill_form	Preencher campos AcroForm (campos ausentes são relatados)	pikepdf
edit_metadata	Definir/limpar Título/Autor/… (docinfo + XMP)	pikepdf
compress_pdf	Comprimir, opcionalmente descendo uma escada de qualidade até atingir target_mb	ghostscript
dependency_status	Sondar ferramentas do sistema + comandos de instalação	—
doctor	Verificação única de integração: imports, sondagem de dependências, caminhos do README	—

Contrato de erros (agentes se auto-roteiam): falhas retornam {"ok": false, "error": "<code>"} — missing_dependency (com install por plataforma), encrypted_pdf (dica: chame unlock_pdf primeiro), wrong_password, output_exists (substituição explícita necessária), invalid_page_range, …

Segurança de saída

• Saídas de arquivo único são gravadas em um arquivo temporário no mesmo diretório e substituídas atomicamente somente após a operação ser bem-sucedida.
• render_pages, extract_images e extract_attachments preparam exportações de vários arquivos em um diretório temporário e as publicam somente após todos os arquivos estarem prontos.
• overwrite tem como padrão false; passe overwrite=true (ou o CLI --overwrite) para substituir uma saída existente. Execuções com falha deixam a saída anterior intacta.
• Senhas de desbloqueio são passadas ao qpdf via stdin, e as senhas de proteção permanecem dentro do processo Python/pikepdf em vez de argumentos de linha de comando.

Exemplos

Em um cliente MCP, basta descrever o resultado — o agente encadeia as ferramentas sozinho, e o contrato de erros o torna auto-roteável (um erro encrypted_pdf diz a ele para chamar unlock_pdf primeiro, e assim por diante). Para uso sem interface, defina uma vez:

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

1 · Digitalização → PDF pesquisável (o carro-chefe)

“contract-scan.pdf é um contrato digitalizado que não consigo pesquisar. Torne-o pesquisável — principalmente em chinês com algum inglês.”

Agente: pdf_info → is_searchable relata baixa densidade de texto → ocr_pdf(path, lang="chi_sim+eng") grava contract-scan_ocr.pdf. A extração de texto e Ctrl+F agora funcionam na saída.

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

2 · PDF criptografado → legível

“locked.pdf está protegido por senha; a senha é hunter2. Desbloqueie-o e resuma a 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 · Redigir segredos antes de compartilhar

“Apague cada ocorrência de 张三 e HT-2026-088 em draft.pdf — deve ser fisicamente irrecuperável.”

Agente: redact_text(queries=["张三", "HT-2026-088"]) → draft_redacted.pdf. As páginas com correspondências são rasterizadas, então as strings desaparecem dos pixels e da camada de texto; outras páginas mantêm o texto selecionável. Verifique executando extract_text na saída: zero correspondências esperadas.

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

Mais receitas — combinar e proteger, comprimir até o alvo, OCR em lote, a cadeia de higiene de publicação (sanitize → edit_metadata → linearize), renderização para visão, localizar e redigir, preenchimento de formulários, resgate de arquivos danificados — no livro de receitas.

Configuração

Env	Padrão	Significado
PDF_TOOLBOX_TESS_LANG	chi_sim+eng	Idiomas padrão de OCR; pacotes ausentes fazem fallback automático (sinalizado via lang_fallback)
PDF_TOOLBOX_WORKSPACE	não definido	Se definido, todas as gravações são confinadas a este diretório; diretórios do sistema são sempre negados

CLI

Tudo também está disponível sem interface (ótimo para scripts e 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

(Use uvx --from pdf-toolbox-mcp … ao instalar do PyPI.)

Segurança e privacidade

• Sem chamadas de rede. Os arquivos nunca saem da máquina.
• Todas as chamadas de subprocesso usam listas de argumentos (sem interpolação de shell); a análise de intervalos de páginas é compartilhada e validada.
• As saídas nunca são substituídas silenciosamente: overwrite=true deve ser passado explicitamente.
• As gravações respeitam PDF_TOOLBOX_WORKSPACE; diretórios do sistema são negados, e saídas preparadas são publicadas atomicamente.
• Senhas nunca são registradas em payloads de erro.
• Conteúdo de PDF não confiável é sinalizado nas descrições das ferramentas (consciência de injeção de prompt).

Conformidade de licença

MIT. As ferramentas do sistema são invocadas como processos independentes (agregação): poppler (GPL-2.0), qpdf (Apache-2.0), tesseract (Apache-2.0), ghostscript (AGPL, opcional); dependências Python ocrmypdf/pikepdf são MPL-2.0. Veja PLAN.md §7 para a tabela completa.

Desenvolvimento

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

Verificação multiplataforma sem sair do 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'

Roteiro: v0.1.4 entrega todas as 25 ferramentas acima; v0.1.5 endureceu a segurança de saída e o isolamento de falhas; v0.1.6 endurece o manuseio de segredos, gravações de configuração e extração de páginas esparsas. Não-objetivos explícitos: editar texto existente, quebrar senhas — veja PLAN.md.

Licença

MIT