JustFill PDF Automation MCP

Rellena formularios PDF existentes desde JSON, Excel o CSV con asignaciones de campos revisadas a través de MCP.

Documentación

Servidor MCP de JustFill

Permite que agentes de IA (Claude, ChatGPT, n8n — cualquier cliente MCP) detecten, revisen y completen campos de formularios PDF a través de justfill.app.

Servidor alojado — sin instalación local

Si tu cliente MCP admite servidores remotos con OAuth, usa esta URL de servidor:

https://justfill.app/api/mcp

Conéctate desde tu cliente, inicia sesión en JustFill y revisa la solicitud de acceso. No necesitas instalar el paquete de Python ni copiar una clave API para esta ruta. El acceso se puede revocar en JustFill en Cuenta → Claves API.

Guía de conexión. El cliente tiene licencia MIT; el procesamiento de PDF utiliza el cupo de tu cuenta de JustFill. Para una primera comprobación, usa un formulario en blanco y valores ficticios, y revisa la vista previa completada antes de exportar. Guarda el diseño revisado para reutilizarlo con nuevos datos cuando aparezca el mismo formulario nuevamente.

Flujo de trabajo por lotes con Excel o CSV

Si los datos de origen ya están en una hoja de cálculo y necesitas una copia completada del mismo PDF existente por fila, un cliente MCP es opcional. El flujo de trabajo guiado en el navegador importa XLSX o CSV, asigna columnas a los campos PDF revisados, previsualiza cada registro y exporta los PDF aprobados en un ZIP.

Prueba la muestra de combinación de correspondencia PDF de cinco filas — sin tarjeta ni llamada de ventas.

Flujos de trabajo n8n listos para importar

Comienza con el JSON de flujo de trabajo determinista en este repositorio. Recopila un PDF y una carga útil JSON, reutiliza los nombres de campos revisados guardados para ese formulario exacto, completa el diseño original y devuelve un enlace de descarga temporal.

El flujo de trabajo corregido también está disponible en la biblioteca de plantillas de n8n. El flujo de trabajo es gratuito para descargar; ejecutarlo usa una cuenta de JustFill y su cupo de procesamiento de PDF. Utiliza nodos integrados, no el nodo comunitario separado de JustFill.

El repositorio también incluye el JSON de flujo de trabajo determinista exacto, un PDF de prueba sintético, evidencia de producción y un flujo de trabajo de visión de dos pasos separado para un formulario desconocido. Ambos llaman al endpoint MCP alojado con nodos HTTP Request estándar y se pueden inspeccionar antes de agregar credenciales.

Inspecciona los flujos de trabajo fuente y la evidencia, o sigue la configuración paso a paso de n8n.

Ejemplo empresarial: recepción recurrente de proveedores

Un equipo de operaciones puede mantener el PDF de recepción requerido por el proveedor sin cambios, guardar su diseño de campos revisado una vez y permitir que n8n asigne datos de proveedores aprobados desde un webhook o registro CRM en ese formulario exacto. El flujo de trabajo devuelve un enlace temporal de PDF completado que se puede revisar antes de subirlo a Drive, adjuntarlo a un borrador de correo electrónico o escribirlo de vuelta en el registro del proveedor. El PDF sintético de recepción de proveedores del repositorio ejercita esta ruta exacta sin datos de clientes.

Extensión de Gemini CLI

Instala las mismas herramientas MCP revisadas más la guía de flujo de trabajo PDF incluida:

gemini extensions install https://github.com/mrmaciej1/justfill-mcp

El manifiesto de la extensión se encuentra en la raíz del repositorio y utiliza el paquete publicado justfill-mcp. Gemini CLI solicita el consentimiento normal de extensiones de terceros antes de habilitarla.

Por qué los agentes pueden confiar en ello

Fuente	Confianza	Qué significa
Plantilla guardada	1.0	Este PDF exacto se completó antes; la geometría está verificada por humanos/agentes. No se ejecuta ML en absoluto.
AcroForm	1.0	El PDF tiene campos de formulario integrados — leídos del archivo, completados de forma nativa.
Detección ML	0.0–0.95	Un borrador honesto. Revísalo visualmente (`render_preview`), corrígelo y luego `save_template` para fijarlo.

La confianza del ML está calibrada: las puntuaciones brutas del detector no son probabilidades (su filtro del lado del servidor acepta cajas desde ~0.02 bruto y auto-acepta en 0.15 bruto), por lo que se asignan a 0–1 para significar lo que esperarías — ≥0.75 "el detector está seguro", 0.4–0.75 "probablemente correcto, echa un vistazo a la vista previa", <0.4 "aceptación límite, verifica". La puntuación bruta del detector se conserva en cada campo como raw_score.

El bucle de corrección (render_preview → add/update/remove_field) existe precisamente porque la detección ML tiene falsos positivos y negativos. Un falso positivo no cuesta nada (déjalo sin completar o elimínalo); un falso negativo es visible en la vista previa y se puede corregir con una llamada a add_field. Una vez revisado, save_template hace que cada futuro completado de ese formulario sea determinista.

Configuración del cliente local

uv tool install justfill-mcp

Autoriza una vez (abre el navegador, un clic mientras estás conectado a justfill.app):

justfill-mcp login

Entonces la configuración no necesita credenciales en absoluto:

{
  "mcpServers": {
    "justfill": { "command": "justfill-mcp" }
  }
}

Para una configuración sin instalación, usa uvx directamente:

{
  "mcpServers": {
    "justfill": {
      "command": "uvx",
      "args": ["justfill-mcp"]
    }
  }
}

Alternativas, en el orden en que el servidor las verifica:

Env JUSTFILL_API_KEY — crea una clave en justfill.app → Cuenta → Claves API y pon "env": {"JUSTFILL_API_KEY": "jf_live_…"} en la configuración.
La clave guardada por justfill-mcp login (~/.config/justfill/credentials.json).
JUSTFILL_EMAIL + JUSTFILL_PASSWORD — alternativa heredada; una clave API es mejor (sin contraseña en archivos de configuración, revocable por cliente, nunca expira a mitad de sesión).

Herramientas

open_pdf(path, min_confidence=0.0, max_pages=10, force_detect=False) — orden de resolución plantilla → AcroForm → ML. También acepta imágenes escaneadas (jpg/png/tiff → convertidas a PDF, de forma determinista, para que las plantillas sigan coincidiendo). force_detect=True ignora una plantilla guardada y vuelve a ejecutar ML.
render_preview(page_index) — imagen de página con cajas de campos etiquetadas (azul = determinista, verde/naranja/rojo = confianza ML)
render_filled_preview(values, page_index) — la misma página con tus valores dibujados en su lugar (las casillas de verificación reciben una X). No consume completados — verifica antes de completar.
list_fields(page_index?)
add_field(x, y, w, h, name, page_index, field_type, align?, vertical_align?) — coordenadas en % de la página, origen en la esquina superior izquierda
update_field(field_id, …) / remove_field(field_id)
update_fields([{field_id, …}, …]) / remove_fields([ids]) — versiones por lotes
prune_fields(field_type?, confidence_below?, width_below?, height_below?, page_index?, exclude_ids?) — elimina en masa el ruido de detección en una sola llamada (criterios combinados con Y, se devuelven los ids eliminados)
fill_pdf(values, output_path, flatten=True) — values = {field_id: text}; responde con warnings para valores que se reducirán/truncarán para ajustarse
save_template(name) — persiste el diseño revisado para completados repetidos deterministas
list_templates()

Alineación de texto: align = left|center|right, vertical_align = top|middle|bottom — se establece por campo (por ejemplo, right para formularios RTL, center para dígitos en cajas). Se persiste en las plantillas.

Ejemplo de flujo de agente

open_pdf("~/forms/w-9.pdf")            → acroform, 27 fields, confidence 1.0
fill_pdf({"f1": "Jane Doe", …}, "~/out/w-9-filled.pdf")

open_pdf("~/forms/scan.jpg")           → converted to PDF; ml, 34 fields
render_preview(0)                      → agent sees noise + one missed line
prune_fields(field_type="cell", width_below=3)   → 16 removed in one call
add_field(x=18, y=62.5, w=40, h=3, name="Phone")
render_filled_preview({…})             → values sit right, no overflow
fill_pdf({…}, "~/out/filled.pdf")
save_template("Client intake form")    → next time: deterministic

Notas

La autenticación es una cuenta regular de justfill.app; los tokens se renuevan automáticamente al expirar.
Las reglas de uso y salida de documentos son aplicadas por el mismo servicio de cuenta que la aplicación web. fill_pdf informa si la salida está limpia o con marca de agua.
Un PDF abierto a la vez por sesión de servidor (por diseño — mantiene los ids estables).
Este repositorio refleja versiones publicadas del cliente MCP (el desarrollo ocurre en un monorepo privado junto con el backend de justfill.app). Los informes de errores y las solicitudes de funciones son muy bienvenidos en el rastreador de problemas aquí.