PDF Toolkit MCP

PDF Toolkit MCP

💼 Disponible para trabajo freelance de integración MCP/IA — DM a @aryansalian03 o vía aryanbv.com

Un kit de herramientas PDF con capacidad de escritura para cualquier cliente MCP. Proporciona 22 herramientas para leer, crear, renderizar, transformar y asegurar PDFs. Esto incluye renderizar páginas a imágenes para que los modelos de visión puedan leer documentos escaneados, construir PDFs desde Markdown o datos estructurados, cifrado AES-256, y operaciones de fusión y división que mantienen intactos los campos de formulario. No tiene dependencias nativas, por lo que se ejecuta localmente desde un solo comando npx.

npx -y @aryanbv/pdf-toolkit-mcp

No necesita archivos de configuración, claves API, Docker ni compilador, y funciona sin conexión.

Descripción general

La mayoría de los servidores PDF para MCP solo leen. Este también escribe: crea documentos desde Markdown o datos estructurados, rellena y aplana formularios, reorganiza la estructura de páginas y aplica cifrado AES-256, todo sin una cadena de herramientas de compilación nativa.

Algunas cosas que vale la pena saber:

• Lee escaneos. pdf_render_pages rasteriza páginas a imágenes, para que un modelo con capacidad de visión pueda leer PDFs escaneados o solo con imágenes que no tienen capa de texto.
• Fusionar, dividir, reordenar y eliminar preservan los campos AcroForm en lugar de descartarlos. Los nombres que colisionan entre entradas se asignan con espacio de nombres por fuente, y cada llamada informa qué preservó, renombró o descartó.
• El cifrado es AES-256 mediante qpdf, no el esquema RC4 heredado.
• Cada motor es WASM o JavaScript puro, por lo que npx funciona en Node 20 y versiones posteriores en Windows, macOS y Linux sin node-gyp, enlaces de canvas ni binarios precompilados.
• Los errores llevan códigos estables, los seguimientos de pila permanecen internos, las colocaciones fuera de página se rechazan en lugar de recortarse silenciosamente, y las respuestas grandes se truncan sin romper el JSON.

Configuración del cliente

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

claude mcp add pdf-toolkit -- npx -y @aryanbv/pdf-toolkit-mcp

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

{
  "servers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

Una vez conectado, pide lo que quieras en lenguaje natural y el cliente selecciona la herramienta y completa los argumentos. Los bloques JSON a continuación muestran los argumentos que acepta cada herramienta, como referencia.

Herramientas

Crear PDFs desde Markdown

Convierte Markdown en un PDF de varias páginas en una sola llamada. Soporta CommonMark y GFM: encabezados, negrita y cursiva, tablas, listas ordenadas y con viñetas, código delimitado y citas en bloque, renderizados con @react-pdf/renderer.

"Crea un PDF desde este informe en Markdown."

Argumentos de pdf_create_from_markdown:

{
  "markdown": "# Quarterly Report\n\nRevenue grew **23% YoY**.\n\n| Region | Q1 2025 | Q1 2026 |\n|--------|---------|--------|\n| Americas | $1.2M | $1.5M |\n| EMEA | $800K | $960K |\n\n## Key Wins\n\n1. 12 new enterprise contracts\n2. Churn down to 3.1%",
  "outputPath": "/path/to/report.pdf",
  "pageSize": "Letter"
}

Las tablas ajustan sus columnas al contenido y respetan la alineación, las listas anidadas se indentan y las líneas de código largas se ajustan. Añade números de página después con pdf_add_page_numbers.

Plantillas

Genera documentos desde datos estructurados usando las plantillas invoice, report y letter.

"Crea una factura para Riverbend Outfitters."

Argumentos de pdf_create_from_template:

{
  "templateName": "invoice",
  "data": {
    "companyName": "Northpoint Design",
    "clientName": "Riverbend Outfitters",
    "invoiceNumber": "2026-0042",
    "invoiceDate": "2026-04-01",
    "items": [
      { "description": "Website redesign", "quantity": 40, "unitPrice": 150 },
      { "description": "Annual hosting", "quantity": 1, "unitPrice": 299 }
    ],
    "taxRate": 18,
    "currency": "USD",
    "paymentTerms": "Net 30"
  },
  "outputPath": "/path/to/invoice.pdf"
}

El parámetro opcional currency de la plantilla invoice acepta un código ISO o un símbolo. Los símbolos seguros para WinAnsi ($ € £ ¥) se renderizan como glifos; un código que Helvetica no puede dibujar, como INR, KRW o TRY, se sustituye por su etiqueta de código ISO (INR 20.00), por lo que cualquier moneda funciona sin errores. El recurso pdf-toolkit://templates lista cada plantilla y los campos que acepta.

Leer PDFs escaneados y solo con imágenes (visión)

Muchos PDFs son escaneos sin capa de texto. pdf_render_pages rasteriza páginas para que un cliente con capacidad de visión pueda leerlos.

"Lee este contrato escaneado."

El modo en línea devuelve páginas como imágenes que el modelo lee directamente (hasta 5 páginas; el DPI se limita automáticamente para proteger la ventana de contexto):

{ "filePath": "/path/to/scanned.pdf", "inline": true }

O escribe archivos de imagen en disco (150 DPI por defecto, primeras 50 páginas, PNG):

{
  "filePath": "/path/to/scanned.pdf",
  "pages": "1-3",
  "dpi": 200,
  "format": "jpeg",
  "outputDir": "/path/to/output"
}

Convertir un PDF a Markdown

"Convierte report.pdf a Markdown para poder resumirlo."

pdf_to_markdown reconstruye el orden de lectura a partir de las posiciones del texto. Agrupa hasta dos columnas de contenido (más bandas de título y pie de página de ancho completo), infiere encabezados a partir del tamaño de fuente y detecta listas. Funciona mejor en PDFs digitales limpios; usa pdf_render_pages para escaneos. Devuelve las primeras 10 páginas por defecto.

{ "filePath": "/path/to/report.pdf", "pages": "1-5" }

Buscar y comparar

"Encuentra cada mención de 'indemnización' en contract.pdf."

Argumentos de pdf_search:

{
  "filePath": "/path/to/contract.pdf",
  "query": "indemnification",
  "caseSensitive": false
}

Cada coincidencia devuelve su número de página y un fragmento circundante. La coincidencia es una subcadena literal sin distinción de mayúsculas por defecto; establece caseSensitive: true para mayúsculas exactas. La búsqueda con expresiones regulares se omite intencionalmente, porque un patrón proporcionado por un atacante puede provocar un retroceso catastrófico (ReDoS) que JavaScript de un solo hilo no puede interrumpir de manera confiable. La expresión regular segura está planificada para una versión posterior.

"¿Qué cambió entre v1.pdf y v2.pdf?"

Argumentos de pdf_compare:

{ "filePathA": "/path/to/v1.pdf", "filePathB": "/path/to/v2.pdf" }

Informa una diferencia de texto página por página (added y removed) y establece identical: true cuando el texto coincide. La diferencia es solo de texto, por lo que los cambios puramente visuales no se detectan.

Fusión, división, eliminación y aplanado que preservan formularios

Fusionar, dividir, reordenar y eliminar páginas preservan los campos AcroForm. Los nombres que colisionan entre entradas se asignan con espacio de nombres por fuente, y cada herramienta devuelve { preserved, renamed, dropped }, donde renamed es una lista de pares { from, to } (dirígete a un campo renombrado por su nombre to después). Estas herramientas y pdf_flatten también devuelven un booleano flattened.

"Fusiona estos tres formularios y aplana el resultado."

Argumentos de pdf_merge:

{
  "filePaths": ["/path/a.pdf", "/path/b.pdf", "/path/c.pdf"],
  "outputPath": "/path/merged.pdf",
  "flatten": true
}

"Elimina las páginas 2 y 5 de report.pdf."

Argumentos de pdf_delete_pages:

{
  "filePath": "/path/report.pdf",
  "pages": "2,5",
  "outputPath": "/path/trimmed.pdf"
}

Usa pdf_flatten por sí solo para integrar los valores de un formulario existente en contenido estático. La ruta de salida debe diferir de la de entrada.

Cifrado

"Cifra report.pdf con la contraseña 'secure123'."

El cifrado es AES-256. Establece contraseñas separadas de usuario (apertura) y propietario (edición) para acceso granular; la contraseña de propietario se establece por defecto a la de usuario cuando se omite.

Argumentos de pdf_encrypt:

{
  "filePath": "/path/report.pdf",
  "outputPath": "/path/report-encrypted.pdf",
  "userPassword": "secure123",
  "ownerPassword": "admin456"
}

Códigos QR y códigos de barras

"Añade un código QR que enlace a nuestro sitio web en la página 1."

pdf_embed_qr_code soporta QR Code, Code128, DataMatrix, EAN-13, PDF417 y Aztec. La posición y el tamaño son configurables, se preserva la relación de aspecto de la simbología, la colocación es consciente de rotación y las colocaciones fuera de página se rechazan en lugar de recortarse.

Indicaciones guiadas

El servidor incluye cinco indicaciones MCP que guían flujos de trabajo de varios pasos para el cliente:

Recursos

pdf-toolkit://templates es un recurso JSON que enumera las plantillas disponibles para pdf_create_from_template y los campos que acepta cada una.

Pruébalo en lenguaje sencillo

• "Crea un PDF a partir de este informe Markdown"
• "Genera una factura para Riverbend Outfitters, 10 horas de consultoría a $150/hora"
• "Combina january.pdf y february.pdf en q1-combined.pdf"
• "Convierte este PDF a Markdown para poder resumirlo"
• "Renderiza este PDF escaneado para que puedas leerlo"
• "Busca 'termination' en contract.pdf"
• "Compara draft-v1.pdf y draft-v2.pdf"
• "Rellena el campo Name con 'John Doe' en application.pdf"
• "Añade una marca de agua CONFIDENTIAL a draft.pdf"
• "Cifra financials.pdf con la contraseña AES-256 'budget2026'"
• "Incorpora un código QR con nuestra URL en la portada"
• "Reordena las páginas como 3,1,2 en report.pdf"

Errores y semántica de salida

• Errores codificados. Los fallos de validación y carga lanzan un PdfError con un código estable, expuesto como Error [CODE]: message (por ejemplo FILE_NOT_FOUND, NOT_A_PDF, PAGE_OUT_OF_RANGE, ENCRYPTED_PDF, RESOURCE_LIMIT). Los clientes pueden ramificar según el código en lugar de analizar el texto del mensaje, y las trazas de pila nunca se filtran.
• Salida de herramientas de escritura. Las herramientas de escritura crean un archivo en outputPath y devuelven esa ruta más su tamaño como texto, ya que MCP no tiene un tipo de contenido de archivo. outputPath puede nombrar un archivo existente y lo sobrescribirá, así que elige una ruta que no colisione con algo que quieras conservar.
• Truncamiento seguro para JSON. Las respuestas están limitadas a 25.000 caracteres. Los payloads de objetos devuelven un envoltorio { truncated, note, preview } válido en lugar de una cadena cortada a mitad de token, de modo que el JSON.parse de un cliente nunca se rompe.

Limitaciones conocidas

• Combinar, dividir, reordenar, eliminar. Los campos de formulario se conservan y los nombres en conflicto se asignan a espacios de nombres y se notifican en renamed como pares { from, to }. Los formularios inusuales que no se pueden reconstruir de forma segura se notifican bajo dropped en lugar de hacer fallar la operación.
• Extracción de texto. Devuelve el orden del flujo del PDF, no el orden visual de lectura. Usa pdf_to_markdown cuando el orden de lectura sea importante; el pdf_extract_text sin procesar puede intercalar diseños de varias columnas.
• PDF a Markdown. Reconstruye hasta dos columnas de contenido (más bandas de título y pie a ancho completo); las páginas con tres o más columnas recurren al orden de lectura de una sola columna. Funciona mejor en PDFs digitales limpios. El contenido tabular se emite como texto posicionado en orden de lectura, no se reconstruye como tablas de Markdown.
• Markdown a PDF. Admite CommonMark y GFM (encabezados, negrita y cursiva, enlaces, listas, tablas, código en bloques, citas y reglas horizontales). No se admiten HTML sin procesar, estado de casillas de listas de tareas, notas al pie ni resaltado de sintaxis de código.
• Comparar. Diff solo de texto; los cambios visuales o de diseño que no alteran el texto no se detectan.
• Inserción de imágenes. Solo JPEG y PNG. Las colocaciones fuera de página se rechazan con un error codificado en lugar de recortarse silenciosamente.
• Fuentes. Las fuentes integradas son solo latinas (WinAnsi). Para escrituras no latinas como árabe, CJK o devanagari, pasa un archivo .ttf o .otf a través de fontPath a pdf_fill_form o pdf_create. Los PDFs de Markdown y plantillas usan Helvetica por defecto.

Stack tecnológico

Un diseño de múltiples motores. Cada motor es WASM o JavaScript puro:

Requisitos

Node.js 20 o posterior. Node 18 y la línea 20.x están al final de su vida útil, por lo que se recomienda Node 22 o 24 LTS.

Desarrollo

npm install        # install dependencies
npm run build      # compile TypeScript
npm test           # run the vitest suite (160 tests)
npm run test:cov   # tests with coverage
npm run lint       # ESLint
npm run format     # Prettier
npm run inspect    # MCP Inspector (requires Node >= 22.7.5)

Consulta CLAUDE.md para notas de arquitectura y contribución.

Licencia

MIT