JustFill PDF Form Automation

JustFill MCP Server

让 AI Agent（Claude、ChatGPT、n8n——任何 MCP 客户端）通过 justfill.app 检测、审核并填写 PDF 表单字段。

在 ChatGPT 中填写 PDF 表单

从 ChatGPT 插件目录安装已发布的 JustFill PDF Forms 插件，然后连接你的 JustFill 账户。此托管方式无需安装 Python 客户端，也无需手动配置 MCP 服务。

试试下面的提示词，并使用这份一页、六个字段的示例：

Use JustFill to open https://justfill.app/examples/chatgpt/project-intake.pdf.
List its fields and show a preview. Do not fill anything yet.

使用虚构值请求填写预览，并在生成 PDF 前进行确认。保存审核后的布局，然后打开同一份原始空白 PDF，为下一个客户或项目填写。保存的模板可在同一个 JustFill 账户中使用；生成的文件遵循该账户的套餐限制。

试用两个项目的示例并下载可编辑的实际结果。示例包含两个虚构客户的提示词、空白 PDF，以及两份带有免费输出水印的生成 PDF。

托管服务——无需本地安装

如果你的 MCP 客户端支持使用 OAuth 的远程服务，请使用此服务 URL：

https://justfill.app/api/mcp

从客户端连接，登录 JustFill，并审核访问请求。使用此方式无需安装 Python 包或复制 API 密钥。可在 JustFill 的“账户 → API Keys”中撤销访问权限。

连接指南。客户端采用 MIT 许可证；PDF 处理使用你 JustFill 账户的额度。首次尝试时，请使用空白表单和虚构值，并在导出前审核填写预览。保存审核后的布局，以便下次遇到同一表单时使用新数据重复填写。

Excel 或 CSV 批量工作流

如果源数据已在电子表格中，并且你需要为每一行数据生成一份填写好的同一份现有 PDF，则 MCP 客户端并非必需。引导式浏览器工作流可导入 XLSX 或 CSV，将列映射到已审核的 PDF 字段，预览每条记录，并将已批准的 PDF 打包为 ZIP 导出。

试用包含五行数据的 PDF 邮件合并示例——无需信用卡，也无需销售人员联系。

可直接导入的 n8n 工作流

从此仓库中的确定性工作流 JSON开始。它会收集 PDF 和 JSON 负载，重用为该特定表单保存的已审核字段名称，填写原始布局，并返回临时下载链接。

该工作流已列入 n8n 模板库。开始新的运行时，请从此仓库导入当前的严格映射 JSON，其中包含合成测试样例及其验证证据。该工作流可免费下载；运行时需要 JustFill 账户及其 PDF 处理额度。它使用内置节点，而非单独的 JustFill 社区节点。

仓库还包含精确的确定性工作流 JSON、合成测试 PDF、生产环境证据，以及一个用于处理陌生表单的独立双阶段视觉工作流。两者都通过标准 HTTP Request 节点调用托管 MCP 端点，可在添加凭据前检查。

查看源工作流和证据，或按照 n8n 分步设置指南操作。

业务示例：定期供应商信息收集

运营团队可以保持供应商要求填写的 PDF 不变，只需保存一次经审核的字段布局，然后让 n8n 将经过批准的供应商数据从 webhook 或 CRM 记录映射到该表单中。工作流会返回一个临时的已填写 PDF 链接，供审核后再上传到 Drive、附加到邮件草稿，或写回供应商记录。仓库中的合成供应商信息收集 PDF 可在不使用客户数据的情况下演练这一完整流程。

Gemini CLI 扩展

安装相同的已审核 MCP 工具，以及随附的 PDF 工作流指南：

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

扩展清单位于仓库根目录，并使用已发布的 justfill-mcp 软件包。Gemini CLI 在启用扩展前会请求常规的第三方扩展授权。

为什么 Agent 可以信任它

来源	可信度	含义
已保存的模板	1.0	之前已填写过这个完全相同的 PDF；其几何布局已由人工/Agent 验证。完全不会运行 ML。
AcroForm	1.0	PDF 内嵌了表单字段——直接从文件读取并以原生方式填写。
ML 检测	0.0–0.95	一份诚实的草稿。请目视检查（render_preview），进行修正，然后运行 save_template 将其固定下来。

ML 置信度经过了校准：检测器的原始分数并非概率（其服务端过滤器会接受原始分数约为 0.02 的框，并在原始分数达到 0.15 时自动接受），因此这些分数会映射到 0–1，以符合预期含义——≥0.75 表示“检测器很确定”，0.4–0.75 表示“可能正确，查看一下预览”，<0.4 表示“处于临界范围，需验证”。每个字段都会保留原始检测器分数，记为 raw_score。

修正循环（render_preview → add/update/remove_field）正是为应对 ML 检测中的误报和漏报而设计的。误报不会造成任何损失（留空或删除即可）；漏报会在预览中显现，只需调用一次 add_field 即可修复。审核完成后，save_template 会让今后对该表单的每次填写都具有确定性。

本地客户端设置

uv tool install justfill-mcp

授权一次（会打开浏览器；登录 justfill.app 后点击一次即可）：

justfill-mcp login

之后，配置完全不需要凭据：

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

如需零安装配置，可直接使用 uvx：

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

其他方式，按服务检查顺序排列：

1. JUSTFILL_API_KEY 环境变量——在 justfill.app → Account → API Keys 创建密钥，并在配置中加入 "env": {"JUSTFILL_API_KEY": "jf_live_…"}。
2. 由 justfill-mcp login 保存的密钥（~/.config/justfill/credentials.json）。
3. JUSTFILL_EMAIL + JUSTFILL_PASSWORD——旧版备用方式；API 密钥更合适（配置文件中无需保存密码，可按客户端撤销，且不会在会话中途过期）。

工具

• open_pdf(path, min_confidence=0.0, max_pages=10, force_detect=False) — 按模板 → AcroForm → ML 的顺序进行解析。也接受扫描图像 （jpg/png/tiff → 确定性地转换为 PDF，因此仍可匹配模板）。force_detect=True 会忽略已保存的模板并重新运行 ML。
• render_preview(page_index) — 显示带有字段框标记的页面图像（蓝色 = 确定性检测，绿色/橙色/红色 = ML 置信度）
• render_filled_preview(values, page_index) — 显示在相应位置填入你的值后的同一页面 （复选框会打上 X）。不消耗填充次数——填充前先检查。
• list_fields(page_index?)
• add_field(x, y, w, h, name, page_index, field_type, align?, vertical_align?) — 坐标以页面百分比表示，原点位于左上角
• update_field(field_id, …) / remove_field(field_id)
• update_fields([{field_id, …}, …]) / remove_fields([ids]) — 批量版本
• prune_fields(field_type?, confidence_below?, width_below?, height_below?, page_index?, exclude_ids?) — 一次调用批量删除检测噪声（条件按 AND 组合，并返回已删除的 ID）
• fill_pdf(values, output_path, flatten=True) — values = {field_id: text}； 对于会缩小或截断以适应字段的值，会通过 warnings 发出提示
• save_template(name) — 保存经审核的布局，以便确定性地重复填充
• list_templates()

文本对齐：align = left|center|right，vertical_align = top|middle|bottom — 可针对每个字段设置（例如，RTL 表单使用 right，方框数字使用 center）。设置会保存在模板中。

Agent 工作流示例

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

说明

• 使用常规的 justfill.app 账号进行身份验证；令牌过期后会自动刷新。
• 用量和文档输出规则由与 Web 应用相同的账号服务强制执行。fill_pdf 会报告输出是否干净或带水印。
• 每个服务会话一次只能打开一个 PDF（这是有意设计的——可保持 ID 稳定）。
• 此代码库镜像 MCP 客户端的已发布版本（开发工作在与 justfill.app 后端配套的私有 monorepo 中进行）。非常欢迎通过此处的问题跟踪器提交 Bug 报告和功能请求。