PDF2Text — Local PDF & Image OCR MCP

Servidor MCP local para extrair texto e Markdown de PDFs, digitalizações e imagens. Usa texto nativo de PDF primeiro e OCR Apple Vision no macOS. Relata páginas ignoradas e avisos. Nenhuma chave de API de OCR necessária.

GitHub
1
Experimente este MCPPatrocinado

Documentação

PDF2Text

Servidor MCP local para agentes de IA e aplicativo para macOS: texto extraído de PDFs, digitalizações e fotos.

Conecte o PDF2Text a um agente com suporte a servidores MCP locais: o agente poderá ler o documento indicado e obter texto ou Markdown para busca, análise e trabalho com seus materiais. O texto pronto de PDFs é extraído diretamente; o OCR é acionado apenas para as páginas que precisam dele. Se páginas forem ignoradas, o agente recebe um aviso explícito.

Conectar MCP · Baixar aplicativo para macOS · Usar CLI

O reconhecimento é feito no seu computador. Ao usar via MCP, o texto extraído é enviado ao cliente; se o cliente usar um modelo em nuvem, o texto pode chegar ao provedor dele.

Início rápido: MCP

A primeira versão do MCP está disponível a partir do código-fonte. São necessários Git, Python 3.11+; para o Apple Vision integrado — macOS 13+. Instalação no Mac:

git clone https://github.com/Timur99/PDF2Text.git
cd PDF2Text
python3 -m venv .venv
.venv/bin/python -m pip install ".[mcp,vision]"
.venv/bin/pdf2text-mcp --help

Nas configurações do cliente MCP, informe o comando e os argumentos (substitua os caminhos absolutos):

{
  "mcpServers": {
    "pdf2text": {
      "command": "/absolute/path/to/PDF2Text/.venv/bin/pdf2text-mcp",
      "args": ["--allow-dir", "/absolute/path/to/documents"]
    }
  }
}

Este é um exemplo para clientes com configuração mcpServers. Em clientes com formulário de conexão, use os mesmos command e args. O cliente inicia o servidor; não é necessário abrir o aplicativo macOS para isso.

Exemplo de solicitação ao agente: "Use o PDF2Text, leia /absolute/path/to/documents/report.pdf e destaque as principais conclusões".

  • extract_text retorna texto, informações sobre páginas e avisos.
  • list_engines mostra os mecanismos disponíveis.
  • Apenas os diretórios indicados via --allow-dir estão disponíveis.
  • No modo auto, o OCR é limitado a 12 páginas. Para reconhecimento completo de uma digitalização, escolha vision ou peça isso ao agente. Limites gerais — 200 páginas de PDF e 80 MB.

Outros sistemas operacionais, parâmetros de ferramentas e detalhes de conexão — em MCP.md.

PDF2Text

Principal diferença

OCR não é o primeiro passo. A maioria das ferramentas processa o PDF inteiro com reconhecimento, mesmo quando já existe uma camada de texto: isso é lento, esquenta o processador e estraga o que já estava perfeito.

O PDF2Text primeiro faz um triage: a biblioteca local pdf-inspector determina o tipo de documento em milissegundos e extrai o texto diretamente das páginas onde ele é legível. O reconhecimento é acionado apenas no restante.

Экран результата: 22 страницы, одна прошла через OCR

Neste documento de 22 páginas, o reconhecimento foi necessário para apenas uma. As demais foram extraídas diretamente; o triage levou 8 ms. A célula azul no mapa de páginas é exatamente essa página; você pode clicar nela para visualizá-la separadamente.

A interface sempre mostra qual caminho gerou o resultado — native, ocr ou hybrid — e quantas páginas passaram por reconhecimento. Se o sistema simplificou ou cortou algo, isso é informado na tela, e não apenas nos logs.

Instalação do aplicativo a partir do código-fonte

São necessários Python 3.11+ e macOS.

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[vision]"

PaddleOCR é o mecanismo reserva, pesa centenas de megabytes e não é necessário para todos:

pip install -e ".[ocr]"

Aplicativo

local-ocr
# http://127.0.0.1:8765

Arraste um PDF ou uma foto para a janela. À esquerda — histórico de tarefas; à direita — resultado com mapa de páginas, fatos do triage e texto. Exportação para Markdown e TXT, exclusão da tarefa junto com o arquivo original.

Linha de comando

pdf2text scan.pdf > out.md

O progresso vai para o stderr, o resultado para o stdout, então a saída pode ser redirecionada e enviada via pipe. O documento é processado em um diretório temporário, que é removido ao final.

FlagO que faz
-o, --output FILEgravar em arquivo em vez de stdout
-e, --engine auto|native|vision|paddleocrmodo de processamento (padrão: auto)
-l, --lang ruidioma de reconhecimento
-f, --format md|txt|jsonformato de saída (padrão: md)
-q, --quietnão exibir progresso

Códigos de retorno: 0 — sucesso, 1 — erro de processamento, 2 — arquivo não encontrado.

Modos

ModoQuando usar
AutomáticoPara tudo. O texto é extraído diretamente; o reconhecimento, apenas onde não há texto
Somente nativoPara PDFs com camada de texto pronta: instantâneo e preciso. Recusa-se a trabalhar em digitalizações
Apple VisionPara digitalizações, fotos e páginas multicolunas. Forçado para todas as páginas
PaddleOCRReserva. Se o Vision falhar em um arquivo específico, ou o sistema não for macOS

O mecanismo de reconhecimento padrão é o Apple Vision. Ele é integrado ao macOS, não ocupa espaço na compilação e, em uma medição de oito páginas, mostrou-se 16 vezes mais rápido que o PaddleOCR, com melhor ordem de leitura em páginas multicolunas: 4,3 s contra 68,4 s. Metodologia e números completos — em DECISIONS.md.

Como funciona o fluxo do documento

файл → проверка → triage (pdf-inspector)
                    ├── страницы с текстом  → берём напрямую
                    └── остальные страницы  → OCR (Vision или PaddleOCR)
                                              ↓
                              сборка → Markdown / TXT / JSON

O domínio não conhece os SDKs dos mecanismos: o roteamento usa funções puras em backend/domain/routing.py, e os mecanismos ficam atrás de um protocolo comum em backend/engines/. Um novo mecanismo é adicionado via adaptador, sem alterar API ou UI.

Privacidade

  • O servidor web escuta apenas em 127.0.0.1; o MCP usa stdio e não abre porta.
  • Triage e OCR funcionam localmente; o servidor não envia o arquivo original para lugar nenhum.
  • O MCP envia o texto extraído ao cliente. O envio posterior para um modelo em nuvem depende do cliente e das configurações dele.
  • O conteúdo dos documentos não é gravado em logs.
  • Não há telemetria.

Compilação do aplicativo para macOS

.venv/bin/pyinstaller desktop/pdf2text.spec --noconfirm \
    --distpath desktop/dist --workpath desktop/build
./desktop/build_app.sh

O resultado é desktop/dist/PDF2Text.app e PDF2Text-<версия>.dmg. Detalhes e identificadores de compilação — em desktop/README.md.

Documentação

DocumentoSobre o quê
ARCHITECTURE.mdComponentes, camadas, contratos dos mecanismos
DESIGN.mdInterface: tokens, componentes, estados
DECISIONS.mdRegistro de decisões com justificativas e medições
PROJECT_PLAN.mdEtapas e critérios de prontidão
MCP.mdInstalação do servidor MCP, conexão e contrato das ferramentas
SPEC-stage-1.5.mdEspecificação da etapa atual

Testes

pip install -e ".[dev,vision]"
pytest