MCP PDF Reader

Extraia texto, imagens e realize OCR em documentos PDF usando o Tesseract OCR.

GitHub
13
Experimente este MCPPatrocinado

Documentação

Servidor MCP PDF Reader (Python + FastMCP)

Um poderoso servidor Model Context Protocol (MCP) construído com FastMCP que fornece capacidades abrangentes de processamento de PDF, incluindo extração de texto, extração de imagens e OCR para leitura de texto dentro de imagens.

Recursos

  • Extração de Texto: Extraia conteúdo de texto das páginas do PDF
  • Extração de Imagens: Extraia todas as imagens de arquivos PDF
  • Capacidades de OCR: Leia texto de imagens usando Tesseract OCR
  • Análise Abrangente: Obtenha estrutura detalhada do PDF e metadados
  • Suporte a Intervalo de Páginas: Processe intervalos específicos de páginas
  • Múltiplos Idiomas: Suporte a OCR para vários idiomas

Pré-requisitos

Dependências do Sistema

Tesseract OCR

Você precisa instalar o Tesseract OCR no seu sistema:

Ubuntu/Debian:

sudo apt update
sudo apt install tesseract-ocr tesseract-ocr-eng

macOS:

brew install tesseract

Windows:

  1. Baixe de: https://github.com/UB-Mannheim/tesseract/wiki
  2. Instale e adicione ao PATH
  3. Ou use: conda install -c conda-forge tesseract

Pacotes de Idiomas Adicionais (Opcional)

# For multiple languages
sudo apt install tesseract-ocr-fra tesseract-ocr-deu tesseract-ocr-spa

Instalação

Início Rápido com UV

  1. Instale o UV (se ainda não estiver instalado):
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  1. Clone/Crie o projeto:
mkdir mcp-pdf-reader-server
cd mcp-pdf-reader-server
  1. Inicialize e instale com UV:
# Copy the files (pdf_reader_server.py and pyproject.toml)
# Then install dependencies
uv sync
  1. Verifique a instalação:
uv run python -c "import pytesseract; print(pytesseract.get_tesseract_version())"

Alternativa: Configuração Manual

Se você preferir a configuração tradicional:

  1. Crie o ambiente virtual:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Instale as dependências:
pip install fastmcp PyMuPDF pytesseract Pillow

Uso

Executando o Servidor

Com UV:

uv run python pdf_reader_server.py

Ou se você tiver o ambiente ativado:

python pdf_reader_server.py

O servidor iniciará e aguardará solicitações MCP em stdin/stdout.

Ferramentas Disponíveis

1. read_pdf_text

Extraia conteúdo de texto das páginas do PDF.

Parâmetros:

  • file_path (string, obrigatório): Caminho para o arquivo PDF
  • page_range (objeto, opcional): Dicionário com números de página start e end

Exemplo:

{
  "file_path": "/path/to/document.pdf",
  "page_range": {"start": 1, "end": 5}
}

2. extract_pdf_images

Extraia todas as imagens de um arquivo PDF.

Parâmetros:

  • file_path (string, obrigatório): Caminho para o arquivo PDF
  • output_dir (string, opcional): Diretório para salvar as imagens
  • page_range (objeto, opcional): Intervalo de páginas a processar

Exemplo:

{
  "file_path": "/path/to/document.pdf",
  "output_dir": "/path/to/images/",
  "page_range": {"start": 1, "end": 3}
}

3. read_pdf_with_ocr

Extraia texto tanto de texto regular quanto de imagens usando OCR.

Parâmetros:

  • file_path (string, obrigatório): Caminho para o arquivo PDF
  • page_range (objeto, opcional): Intervalo de páginas a processar
  • ocr_language (string, opcional): Código do idioma do OCR (padrão: "eng")

Exemplo:

{
  "file_path": "/path/to/document.pdf",
  "ocr_language": "eng+fra",
  "page_range": {"start": 1, "end": 10}
}

Idiomas de OCR Suportados:

  • eng - Inglês
  • fra - Francês
  • deu - Alemão
  • spa - Espanhol
  • eng+fra - Múltiplos idiomas

4. get_pdf_info

Obtenha metadados abrangentes e estatísticas sobre um PDF.

Parâmetros:

  • file_path (string, obrigatório): Caminho para o arquivo PDF

5. analyze_pdf_structure

Analise a estrutura e a distribuição de conteúdo de um PDF.

Parâmetros:

  • file_path (string, obrigatório): Caminho para o arquivo PDF

Configuração com Claude Desktop

Com UV

Adicione isto ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-reader": {
      "command": "uv",
      "args": ["run", "python", "/path/to/your/pdf_reader_server.py"],
      "cwd": "/path/to/your/mcp-pdf-reader-server"
    }
  }
}

Com Ambiente Virtual

{
  "mcpServers": {
    "pdf-reader": {
      "command": "/path/to/your/.venv/bin/python",
      "args": ["/path/to/your/pdf_reader_server.py"]
    }
  }
}

Python do Sistema

{
  "mcpServers": {
    "pdf-reader": {
      "command": "python",
      "args": ["/path/to/your/pdf_reader_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/your/.venv/lib/python3.x/site-packages"
      }
    }
  }
}

Exemplos de Respostas

Resposta de Extração de Texto

{
  "success": true,
  "file_path": "/path/to/document.pdf",
  "pages_processed": "1-3",
  "total_pages": 10,
  "pages_text": [
    {
      "page_number": 1,
      "text": "Page 1 content...",
      "word_count": 125
    }
  ],
  "combined_text": "All text combined...",
  "total_word_count": 1250,
  "total_character_count": 8750
}

Resposta de OCR

{
  "success": true,
  "file_path": "/path/to/document.pdf",
  "pages_processed": "1-2",
  "ocr_language": "eng",
  "pages_data": [
    {
      "page_number": 1,
      "text": "Regular text from PDF...",
      "ocr_text": "Text extracted from images...",
      "images_with_text": [
        {
          "image_index": 1,
          "ocr_text": "Text from image 1",
          "confidence": "high"
        }
      ],
      "combined_text": "Combined text and OCR...",
      "text_word_count": 100,
      "ocr_word_count": 25
    }
  ],
  "summary": {
    "total_text_word_count": 200,
    "total_ocr_word_count": 50,
    "combined_word_count": 250,
    "images_processed": 3
  },
  "all_text_combined": "All extracted text..."
}

Considerações de Desempenho

Desempenho do OCR

  • O processamento de OCR pode ser lento para imagens grandes
  • Considere processar intervalos de páginas menores para resultados mais rápidos
  • Imagens menores que 50x50 pixels são automaticamente ignoradas

Uso de Memória

  • PDFs grandes com muitas imagens podem consumir memória significativa
  • O servidor processa páginas sequencialmente para gerenciar o uso de memória
  • As imagens extraídas são salvas em disco para reduzir a pressão na memória

Dicas de Otimização

  1. Use intervalos de páginas para documentos grandes
  2. Especifique diretórios de saída para extração de imagens para evitar acúmulo de arquivos temporários
  3. Escolha idiomas de OCR apropriados para melhorar precisão e velocidade
  4. Pré-processe imagens se a qualidade do OCR for ruim (considere adicionar OpenCV)

Solução de Problemas

Problemas Comuns

  1. Tesseract não encontrado:

    TesseractNotFoundError: tesseract is not installed
    • Instale o pacote de sistema Tesseract OCR
    • Certifique-se de que está no seu PATH

  2. Erros de permissão:

    • Certifique-se de que o processo Python tenha acesso de leitura aos arquivos PDF
    • Certifique-se de ter acesso de escrita aos diretórios de saída

  3. Resultados ruins de OCR:

    • Tente diferentes códigos de idioma de OCR
    • Considere o pré-processamento de imagens
    • Verifique se as imagens têm resolução alta o suficiente

  4. Erros de memória:

    • Processe intervalos de páginas menores
    • Feche outros aplicativos
    • Considere aumentar a RAM disponível

Modo de Depuração

Execute com registro de depuração usando UV:

PYTHONUNBUFFERED=1 uv run python pdf_reader_server.py

Ou com Python regular:

PYTHONUNBUFFERED=1 python pdf_reader_server.py

Testando OCR

Teste o Tesseract diretamente:

tesseract --list-langs
tesseract image.png output.txt

Dependências

  • fastmcp: Framework moderno de servidor MCP
  • PyMuPDF: Processamento e renderização rápida de PDF
  • pytesseract: Wrapper Python para Tesseract OCR
  • Pillow: Biblioteca de processamento de imagens
  • tesseract-ocr: Mecanismo de OCR do sistema

Recursos Avançados

Configuração Personalizada de OCR

Você pode modificar a configuração de OCR no código:

ocr_text = pytesseract.image_to_string(
    pil_image, 
    lang=ocr_language,
    config='--psm 6 -c tessedit_char_whitelist=0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz '
)

Pré-processamento de Imagens

Para melhores resultados de OCR, considere adicionar pré-processamento de imagens:

# Add to requirements: opencv-python, numpy
import cv2
import numpy as np

# Preprocessing example
def preprocess_image(image):
    gray = cv2.cvtColor(np.array(image), cv2.COLOR_RGB2GRAY)
    thresh = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY | cv2.THRESH_OTSU)[1]
    return Image.fromarray(thresh)

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Adicione testes para novas funcionalidades
  4. Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.