JustFill PDF Automation MCP

Preencha formulários PDF existentes a partir de JSON, Excel ou CSV com mapeamentos de campos revisados via MCP.

Documentação

Servidor MCP JustFill

Permita que agentes de IA (Claude, ChatGPT, n8n — qualquer cliente MCP) detectem, revisem e preencham campos de formulários PDF através do justfill.app.

Servidor hospedado — sem instalação local

Se o seu cliente MCP suporta servidores remotos com OAuth, use esta URL de servidor:

https://justfill.app/api/mcp

Conecte-se pelo seu cliente, faça login no JustFill e revise a solicitação de acesso. Você não precisa instalar o pacote Python ou copiar uma chave de API para este caminho. O acesso pode ser revogado no JustFill em Conta → Chaves de API.

Guia de conexão. O cliente é licenciado sob MIT; o processamento de PDF usa a cota da sua conta JustFill. Para uma primeira verificação, use um formulário em branco e valores fictícios, e revise a pré-visualização preenchida antes de exportar. Salve o layout revisado para reutilizá-lo com novos dados quando o mesmo formulário aparecer novamente.

Fluxo de trabalho em lote com Excel ou CSV

Se os dados de origem já estiverem em uma planilha e você precisar de uma cópia preenchida do mesmo PDF existente por linha, um cliente MCP é opcional. O fluxo de trabalho guiado no navegador importa XLSX ou CSV, mapeia colunas para os campos de PDF revisados, pré-visualiza cada registro e exporta os PDFs aprovados em um ZIP.

Experimente a amostra de mala direta de PDF com cinco linhas — sem cartão de crédito ou ligação de vendas.

Fluxos de trabalho n8n prontos para importação

Comece com o JSON de fluxo de trabalho determinístico neste repositório. Ele coleta um PDF e um payload JSON, reutiliza os nomes de campos revisados salvos para aquele formulário exato, preenche o layout original e retorna um link de download temporário.

O fluxo de trabalho corrigido também está disponível na biblioteca de modelos do n8n. O fluxo de trabalho é gratuito para baixar; executá-lo usa uma conta JustFill e sua cota de processamento de PDF. Ele usa nós integrados, não o nó separado da comunidade JustFill.

O repositório também inclui o JSON exato do fluxo de trabalho determinístico, um PDF de teste sintético, evidências de produção e um fluxo de trabalho separado de visão em duas etapas para um formulário desconhecido. Ambos chamam o endpoint MCP hospedado com nós padrão de Solicitação HTTP e podem ser inspecionados antes de adicionar credenciais.

Inspecione os fluxos de trabalho de origem e as evidências, ou siga a configuração passo a passo do n8n.

Exemplo de negócio: recebimento recorrente de fornecedores

Uma equipe de operações pode manter o PDF de recebimento exigido pelo fornecedor inalterado, salvar seu layout de campos revisado uma vez e deixar o n8n mapear dados de fornecedores aprovados de um webhook ou registro de CRM para esse formulário exato. O fluxo de trabalho retorna um link temporário do PDF preenchido que pode ser revisado antes de ser enviado ao Drive, anexado a um e-mail rascunho ou gravado de volta no registro do fornecedor. O PDF sintético de recebimento de fornecedor do repositório exercita exatamente esse caminho sem dados de clientes.

Extensão do Gemini CLI

Instale as mesmas ferramentas MCP revisadas mais as orientações incluídas de fluxo de trabalho de PDF:

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

O manifesto da extensão fica na raiz do repositório e usa o pacote publicado justfill-mcp. O Gemini CLI solicita o consentimento normal de extensão de terceiros antes de ativá-la.

Por que os agentes podem confiar nele

Fonte	Confiança	O que significa
Modelo salvo	1.0	Este PDF exato foi preenchido antes; a geometria é verificada por humano/agente. Nenhum ML é executado.
AcroForm	1.0	O PDF tem campos de formulário incorporados — lidos do arquivo, preenchidos nativamente.
Detecção por ML	0.0–0.95	Um rascunho honesto. Revise-o visualmente (`render_preview`), corrija-o e depois `save_template` para fixá-lo.

A confiança do ML é calibrada: as pontuações brutas do detector não são probabilidades (seu filtro no lado do servidor aceita caixas a partir de ~0.02 bruto e aceita automaticamente a 0.15 bruto), então elas são mapeadas para 0–1 para significar o que você esperaria — ≥0.75 "o detector tem certeza", 0.4–0.75 "provavelmente certo, dê uma olhada na pré-visualização", <0.4 "aceitação limítrofe, verifique". A pontuação bruta do detector é mantida em cada campo como raw_score.

O loop de correção (render_preview → add/update/remove_field) existe precisamente porque a detecção por ML tem falsos positivos e negativos. Um falso positivo não custa nada (deixe-o sem preencher ou remova-o); um falso negativo é visível na pré-visualização e corrigível com uma chamada de add_field. Uma vez revisado, save_template torna cada preenchimento futuro desse formulário determinístico.

Configuração do cliente local

uv tool install justfill-mcp

Autorize uma vez (abre o navegador, um clique enquanto estiver logado no justfill.app):

justfill-mcp login

Então a configuração não precisa de nenhuma credencial:

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

Para uma configuração sem instalação, use uvx diretamente:

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

Alternativas, na ordem em que o servidor as verifica:

Env JUSTFILL_API_KEY — crie uma chave em justfill.app → Conta → Chaves de API e coloque "env": {"JUSTFILL_API_KEY": "jf_live_…"} na configuração.
A chave salva por justfill-mcp login (~/.config/justfill/credentials.json).
JUSTFILL_EMAIL + JUSTFILL_PASSWORD — fallback legado; uma chave de API é melhor (sem senha em arquivos de configuração, revogável por cliente, nunca expira no meio da sessão).

Ferramentas

open_pdf(path, min_confidence=0.0, max_pages=10, force_detect=False) — ordem de resolução modelo → AcroForm → ML. Também aceita imagens escaneadas (jpg/png/tiff → convertidas para PDF, deterministicamente, para que os modelos ainda correspondam). force_detect=True ignora um modelo salvo e reexecuta o ML.
render_preview(page_index) — imagem da página com caixas de campos rotuladas (azul = determinístico, verde/laranja/vermelho = confiança do ML)
render_filled_preview(values, page_index) — a mesma página com seus valores desenhados no lugar (caixas de seleção recebem um X). Não custa preenchimentos — verifique antes de preencher.
list_fields(page_index?)
add_field(x, y, w, h, name, page_index, field_type, align?, vertical_align?) — coordenadas em % da página, origem no canto superior esquerdo
update_field(field_id, …) / remove_field(field_id)
update_fields([{field_id, …}, …]) / remove_fields([ids]) — versões em lote
prune_fields(field_type?, confidence_below?, width_below?, height_below?, page_index?, exclude_ids?) — exclusão em massa de ruído de detecção em uma chamada (critérios combinados com E, ids removidos retornados)
fill_pdf(values, output_path, flatten=True) — values = {field_id: text}; responde com warnings para valores que serão reduzidos/truncados para caber
save_template(name) — persiste o layout revisado para preenchimentos repetidos determinísticos
list_templates()

Alinhamento de texto: align = left|center|right, vertical_align = top|middle|bottom — definido por campo (ex.: right para formulários RTL, center para dígitos em caixas). Persistido em modelos.

Exemplo de fluxo 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

A autenticação é uma conta regular do justfill.app; os tokens são renovados automaticamente na expiração.
As regras de uso e saída de documentos são aplicadas pelo mesmo serviço de conta que o aplicativo web. fill_pdf informa se a saída está limpa ou com marca d'água.
Um PDF aberto por vez por sessão de servidor (por design — mantém os ids estáveis).
Este repositório espelha versões publicadas do cliente MCP (o desenvolvimento acontece em um monorepo privado junto com o backend do justfill.app). Relatórios de bugs e solicitações de recursos são muito bem-vindos no rastreador de problemas aqui.