{
  "markdown": "# JustFill MCP Server\n\nLet AI agents (Claude, ChatGPT, n8n — any MCP client) detect, review and fill\nPDF form fields through [justfill.app](https://justfill.app).\n\n<!-- mcp-name: io.github.mrmaciej1/justfill-pdf-forms -->\n\n## Excel or CSV batch workflow\n\nIf the source data is already in a spreadsheet and you need one filled copy of\nthe same existing PDF per row, an MCP client is optional. The guided browser\nworkflow imports XLSX or CSV, maps columns to reviewed PDF fields, previews each\nrecord, and exports the approved PDFs in a ZIP.\n\n[Try the five-row PDF mail merge sample](https://justfill.app/solutions/fill-pdf-from-excel?utm_campaign=b2b_pdf_automation_2026q3&utm_content=mcp_readme_excel_batch)\n— no card or sales call.\n\n## Import-ready n8n workflows\n\nStart with the\n[free reviewed template in the official n8n workflow catalog](https://n8n.io/workflows/17274-fill-pdf-forms-from-json-data-with-justfill-and-a-form-trigger/).\nIt collects a PDF and JSON payload, reuses the reviewed field names saved for\nthat exact form, fills the original layout and returns a temporary download\nlink.\n\nThe repository also includes the exact deterministic workflow JSON, synthetic\ntest PDF, production evidence and a separate two-pass vision workflow for an\nunfamiliar form. Both call the hosted MCP endpoint with standard HTTP Request\nnodes and can be inspected before adding credentials.\n\n[Inspect the source workflows and evidence](examples/n8n/README.md), or follow the\n[step-by-step n8n setup](https://justfill.app/integrations/n8n-fill-pdf-forms?utm_campaign=b2b_pdf_automation_2026q3&utm_content=mcp_readme_n8n_workflows).\n\n### Business example: recurring supplier intake\n\nAn operations team can keep the supplier's required intake PDF unchanged,\nsave its reviewed field layout once, and let n8n map approved vendor data from\na webhook or CRM record into that exact form. The workflow returns a temporary\nfilled-PDF link that can be reviewed before it is uploaded to Drive, attached\nto a draft email, or written back to the vendor record. The repository's\nsynthetic supplier-intake PDF exercises this exact path without customer data.\n\n## Gemini CLI extension\n\nInstall the same reviewed MCP tools plus the included PDF workflow guidance:\n\n```bash\ngemini extensions install https://github.com/mrmaciej1/justfill-mcp\n```\n\nThe extension manifest lives at the repository root and uses the published\n`justfill-mcp` package. Gemini CLI asks for normal third-party extension consent\nbefore enabling it.\n\n## Why agents can trust it\n\n| Source | Confidence | What it means |\n|---|---|---|\n| **Saved template** | 1.0 | This exact PDF was filled before; geometry is human/agent-verified. No ML runs at all. |\n| **AcroForm** | 1.0 | The PDF has embedded form fields — read from the file, filled natively. |\n| **ML detection** | 0.0–0.95 | An honest draft. Review it visually (`render_preview`), fix it, then `save_template` to lock it in. |\n\nML confidence is *calibrated*: the detector's raw scores are not\nprobabilities (its server-side filter accepts boxes from raw ~0.02 and\nauto-accepts at raw 0.15), so they are mapped onto 0–1 to mean what you'd\nexpect — ≥0.75 \"detector is sure\", 0.4–0.75 \"probably right, glance at the\npreview\", <0.4 \"borderline accept, verify\". The raw detector score is kept\non each field as `raw_score`.\n\nThe correction loop (`render_preview` → `add/update/remove_field`) exists\nprecisely because ML detection has false positives and negatives. A false\npositive costs nothing (leave it unfilled or remove it); a false negative is\nvisible on the preview and fixable with one `add_field` call. Once reviewed,\n`save_template` makes every future fill of that form deterministic.\n\n## Setup\n\n```bash\nuv tool install justfill-mcp\n```\n\nAuthorize once (opens the browser, one click while logged in to justfill.app):\n\n```bash\njustfill-mcp login\n```\n\nThen the config needs no credentials at all:\n\n```json\n{\n  \"mcpServers\": {\n    \"justfill\": { \"command\": \"justfill-mcp\" }\n  }\n}\n```\n\nFor a zero-install configuration, use `uvx` directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"justfill\": {\n      \"command\": \"uvx\",\n      \"args\": [\"justfill-mcp\"]\n    }\n  }\n}\n```\n\nAlternatives, in the order the server checks them:\n\n1. `JUSTFILL_API_KEY` env — create a key at justfill.app → Account → API Keys\n   and put `\"env\": {\"JUSTFILL_API_KEY\": \"jf_live_…\"}` in the config.\n2. The key saved by `justfill-mcp login` (`~/.config/justfill/credentials.json`).\n3. `JUSTFILL_EMAIL` + `JUSTFILL_PASSWORD` — legacy fallback; an API key is\n   better (no password in config files, revocable per client, never expires\n   mid-session).\n\n## Tools\n\n- `open_pdf(path, min_confidence=0.0, max_pages=10, force_detect=False)` —\n  template → AcroForm → ML resolution order. Accepts scanned images too\n  (jpg/png/tiff → converted to PDF, deterministically, so templates still\n  match). `force_detect=True` ignores a saved template and re-runs ML.\n- `render_preview(page_index)` — page image with labeled field boxes (blue = deterministic, green/orange/red = ML confidence)\n- `render_filled_preview(values, page_index)` — the same page with your values\n  drawn in place (checkboxes get an X). Costs no fills — check before you fill.\n- `list_fields(page_index?)`\n- `add_field(x, y, w, h, name, page_index, field_type, align?, vertical_align?)` — coords in % of page, top-left origin\n- `update_field(field_id, …)` / `remove_field(field_id)`\n- `update_fields([{field_id, …}, …])` / `remove_fields([ids])` — batch versions\n- `prune_fields(field_type?, confidence_below?, width_below?, height_below?, page_index?, exclude_ids?)` —\n  bulk-delete detection noise in one call (criteria AND-ed, removed ids returned)\n- `fill_pdf(values, output_path, flatten=True)` — `values` = `{field_id: text}`;\n  responds with `warnings` for values that will be shrunk/truncated to fit\n- `save_template(name)` — persist the reviewed layout for deterministic repeat fills\n- `list_templates()`\n\nText alignment: `align` = `left|center|right`, `vertical_align` =\n`top|middle|bottom` — set per field (e.g. `right` for RTL forms, `center` for\nboxed digits). Persisted in templates.\n\n## Example agent flow\n\n```\nopen_pdf(\"~/forms/w-9.pdf\")            → acroform, 27 fields, confidence 1.0\nfill_pdf({\"f1\": \"Jane Doe\", …}, \"~/out/w-9-filled.pdf\")\n```\n\n```\nopen_pdf(\"~/forms/scan.jpg\")           → converted to PDF; ml, 34 fields\nrender_preview(0)                      → agent sees noise + one missed line\nprune_fields(field_type=\"cell\", width_below=3)   → 16 removed in one call\nadd_field(x=18, y=62.5, w=40, h=3, name=\"Phone\")\nrender_filled_preview({…})             → values sit right, no overflow\nfill_pdf({…}, \"~/out/filled.pdf\")\nsave_template(\"Client intake form\")    → next time: deterministic\n```\n\n## Notes\n\n- Auth is a regular justfill.app account; tokens auto-refresh on expiry.\n- Usage and document-output rules are enforced by the same account service as\n  the web app. `fill_pdf` reports whether the output is clean or watermarked.\n- One PDF open at a time per server session (by design — keeps ids stable).\n- This repository mirrors released versions of the MCP client (development\n  happens in a private monorepo alongside the justfill.app backend). Bug\n  reports and feature requests are very welcome in the issue tracker here.\n",
  "bytes": 7277,
  "sha": "71835de48110349d58123ff4d08ff9e8eb6c96c8e44722ab1f1da5afba26f87d",
  "repo_slug": "mrmaciej1/justfill-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mrmaciej1_justfill_pdf_forms_c6abd5a2/readme"
}