MCP PDF Reader

Extraer texto, imágenes y realizar OCR en documentos PDF utilizando Tesseract OCR.

GitHub
13
Prueba este MCPPatrocinado

Documentación

Servidor MCP PDF Reader (Python + FastMCP)

Un potente servidor de Model Context Protocol (MCP) construido con FastMCP que proporciona capacidades integrales de procesamiento de PDF, incluyendo extracción de texto, extracción de imágenes y OCR para leer texto dentro de imágenes.

Características

  • Extracción de texto: Extrae contenido de texto de páginas PDF
  • Extracción de imágenes: Extrae todas las imágenes de archivos PDF
  • Capacidades OCR: Lee texto de imágenes usando Tesseract OCR
  • Análisis integral: Obtén estructura detallada y metadatos del PDF
  • Soporte de rango de páginas: Procesa rangos de páginas específicos
  • Múltiples idiomas: Soporte OCR para varios idiomas

Requisitos previos

Dependencias del sistema

Tesseract OCR

Necesitas instalar Tesseract OCR en tu sistema:

Ubuntu/Debian:

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

macOS:

brew install tesseract

Windows:

  1. Descárgalo desde: https://github.com/UB-Mannheim/tesseract/wiki
  2. Instálalo y agrégalo al PATH
  3. O usa: conda install -c conda-forge tesseract

Paquetes de idiomas adicionales (Opcional)

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

Instalación

Inicio rápido con UV

  1. Instala UV (si aún no está instalado):
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  1. Clona/Crea el proyecto:
mkdir mcp-pdf-reader-server
cd mcp-pdf-reader-server
  1. Inicializa e instala con UV:
# Copy the files (pdf_reader_server.py and pyproject.toml)
# Then install dependencies
uv sync
  1. Verifica la instalación:
uv run python -c "import pytesseract; print(pytesseract.get_tesseract_version())"

Alternativa: Configuración manual

Si prefieres la configuración tradicional:

  1. Crea un entorno virtual:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Instala las dependencias:
pip install fastmcp PyMuPDF pytesseract Pillow

Uso

Ejecutar el servidor

Con UV:

uv run python pdf_reader_server.py

O si tienes el entorno activado:

python pdf_reader_server.py

El servidor se iniciará y escuchará solicitudes MCP en stdin/stdout.

Herramientas disponibles

1. read_pdf_text

Extrae contenido de texto de páginas PDF.

Parámetros:

  • file_path (cadena, obligatorio): Ruta al archivo PDF
  • page_range (objeto, opcional): Diccionario con start y end números de página

Ejemplo:

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

2. extract_pdf_images

Extrae todas las imágenes de un archivo PDF.

Parámetros:

  • file_path (cadena, obligatorio): Ruta al archivo PDF
  • output_dir (cadena, opcional): Directorio para guardar las imágenes
  • page_range (objeto, opcional): Rango de páginas a procesar

Ejemplo:

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

3. read_pdf_with_ocr

Extrae texto tanto de texto regular como de imágenes usando OCR.

Parámetros:

  • file_path (cadena, obligatorio): Ruta al archivo PDF
  • page_range (objeto, opcional): Rango de páginas a procesar
  • ocr_language (cadena, opcional): Código de idioma OCR (predeterminado: "eng")

Ejemplo:

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

Idiomas OCR compatibles:

  • eng - Inglés
  • fra - Francés
  • deu - Alemán
  • spa - Español
  • eng+fra - Múltiples idiomas

4. get_pdf_info

Obtén metadatos y estadísticas completos sobre un PDF.

Parámetros:

  • file_path (cadena, obligatorio): Ruta al archivo PDF

5. analyze_pdf_structure

Analiza la estructura y distribución de contenido de un PDF.

Parámetros:

  • file_path (cadena, obligatorio): Ruta al archivo PDF

Configuración con Claude Desktop

Con UV

Agrega esto a tu 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"
    }
  }
}

Con entorno virtual

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

Python del 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"
      }
    }
  }
}

Respuestas de ejemplo

Respuesta de extracción 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
}

Respuesta 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..."
}

Consideraciones de rendimiento

Rendimiento OCR

  • El procesamiento OCR puede ser lento para imágenes grandes
  • Considera procesar rangos de páginas más pequeños para obtener resultados más rápidos
  • Las imágenes más pequeñas de 50x50 píxeles se omiten automáticamente

Uso de memoria

  • Los PDF grandes con muchas imágenes pueden consumir memoria significativa
  • El servidor procesa las páginas secuencialmente para gestionar el uso de memoria
  • Las imágenes extraídas se guardan en disco para reducir la presión de memoria

Consejos de optimización

  1. Usa rangos de páginas para documentos grandes
  2. Especifica directorios de salida para la extracción de imágenes y evitar acumulación de archivos temporales
  3. Elige idiomas OCR apropiados para mejorar precisión y velocidad
  4. Preprocesa imágenes si la calidad del OCR es deficiente (considera agregar OpenCV)

Solución de problemas

Problemas comunes

  1. Tesseract no encontrado:

    TesseractNotFoundError: tesseract is not installed
    • Instala el paquete del sistema Tesseract OCR
    • Asegúrate de que esté en tu PATH

  2. Errores de permisos:

    • Asegúrate de que el proceso de Python tenga acceso de lectura a los archivos PDF
    • Asegúrate de tener acceso de escritura a los directorios de salida

  3. Resultados OCR deficientes:

    • Prueba con diferentes códigos de idioma OCR
    • Considera el preprocesamiento de imágenes
    • Verifica si las imágenes tienen suficiente resolución

  4. Errores de memoria:

    • Procesa rangos de páginas más pequeños
    • Cierra otras aplicaciones
    • Considera aumentar la RAM disponible

Modo de depuración

Ejecuta con registro de depuración usando UV:

PYTHONUNBUFFERED=1 uv run python pdf_reader_server.py

O con Python regular:

PYTHONUNBUFFERED=1 python pdf_reader_server.py

Prueba de OCR

Prueba Tesseract directamente:

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

Dependencias

  • fastmcp: Marco moderno de servidor MCP
  • PyMuPDF: Procesamiento y renderizado rápido de PDF
  • pytesseract: Envoltorio de Python para Tesseract OCR
  • Pillow: Biblioteca de procesamiento de imágenes
  • tesseract-ocr: Motor OCR del sistema

Características avanzadas

Configuración personalizada de OCR

Puedes modificar la configuración de OCR en el código:

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

Preprocesamiento de imágenes

Para mejores resultados de OCR, considera agregar preprocesamiento de imágenes:

# 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)

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Agrega pruebas para la nueva funcionalidad
  4. Envía una solicitud de extracción

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.