formfill-mcp

<div align="center"> <img src="assets/logo.png" alt="FormFill MCP" width="120" /> <h1>FormFill MCP</h1> <p><strong>Fill any PDF form from your AI agent — in a single tool call.</strong></p>

<p>Tax forms · HR paperwork · Legal documents · Lease agreements · Insurance claims</p> <p>If it has fillable fields, FormFill can fill it.</p>

Get API Key · View on Smithery · Built by Plenitudo AI

Listed on: Smithery · Glama

</div>

---

How It Works

 ┌─────────────────┐        ┌─────────────────┐        ┌─────────────────┐
 │  1. Inspect     │        │  2. Fill         │        │  3. Done        │
 │                 │   →    │                 │   →    │                 │
 │  list_form_     │        │  fill_form       │        │  Filled PDF     │
 │  fields         │        │                 │        │  saved to disk  │
 │                 │        │                 │        │                 │
 │  Returns every  │        │  Writes values, │        │  Open in        │
 │  field name,    │        │  saves output   │        │  Preview or     │
 │  type & value   │        │  file           │        │  send anywhere  │
 └─────────────────┘        └─────────────────┘        └─────────────────┘

Most AI workflows collapse at the last mile: the agent understands the form but can't write to it. FormFill closes that gap with three focused tools.

---

Tools

| Tool | Description | When to use | |---|---|---| | list_form_fields | Returns every fillable field — name, type, and current value | First step: discover what's in the form | | fill_form | Fill a PDF with provided field values and save the result | Standard forms (1–5 pages) | | fill_form_multipage | Same as fill_form, page-by-page for large documents | Complex multi-page forms (6+ pages) |

---

Works With

Any MCP-compatible host:

• Claude Desktop — add to claude_desktop_config.json
• Cursor — MCP server config
• Cline — same config pattern
• Continue — same config pattern
• Any agent that supports the Model Context Protocol

---

Supported Form Types

| Category | Examples | |---|---| | Tax | W-9, W-4, 1040, Schedule C, state forms | | HR | I-9, onboarding packets, benefits enrollment, PTO | | Legal | NDAs, lease agreements, contracts, disclosures | | Insurance | Claims forms, enrollment applications | | Real Estate | Purchase agreements, rental applications, disclosures | | Education | Admissions, financial aid, transcripts |

---

Pricing

| Tier | Price | Monthly Fills | |---|---|---| | Free | $0 | 50 fills | | Pro | $9.99 / month | Unlimited |

Get your API key at formfill.plenitudo.ai

---

Quick Start

1. Get an API key

Sign up at formfill.plenitudo.ai — free tier available immediately.

2. Connect to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "formfill": {
      "command": "/absolute/path/to/formfill-mcp/venv/bin/python",
      "args": ["/absolute/path/to/formfill-mcp/server.py", "--stdio"]
    }
  }
}

Replace the paths with your actual install location. Fully quit and reopen Claude Desktop (Cmd+Q — just closing the window is not enough). You'll see the 🔨 tools icon — FormFill is connected.

Remote HTTP endpoint (Cursor, Cline, any HTTP MCP client):

https://formfill.plenitudo.ai/mcp

3. Fill your first form

List the fillable fields in /Users/me/Desktop/w9.pdf using API key ff_free_abc123

Fill the form at /Users/me/Desktop/w9.pdf with:
  name: Jane Smith
  TIN: 12-3456789
  address: 123 Main St, Austin TX 78701
Save to /Users/me/Desktop/w9_filled.pdf
API key: ff_free_abc123

---

Example Prompts

W-9 (tax):

Fill the W-9 at ~/Desktop/fw9.pdf with my name "John Smith", SSN "123-45-6789",
address "456 Oak Ave, Boston MA 02101". Business type: Individual/sole proprietor.
Save to ~/Desktop/fw9_filled.pdf. API key: ff_free_abc123

Rental application:

Fill the rental application at ~/Desktop/rental_app.pdf with these values:
[paste field values]. Save to ~/Desktop/rental_filled.pdf. API key: ff_free_abc123

Multi-page contract:

Fill the 8-page NDA at ~/Desktop/nda.pdf. My name: Jane Smith, Company: Acme Corp,
Date: March 28 2026. Use fill_form_multipage. API key: ff_free_abc123

---

Response Format

Success:

{
  "ok": true,
  "output_path": "/Users/me/forms/w9_filled.pdf",
  "fields_filled": 12,
  "invalid_fields": []
}

Error:

{"ok": false, "error": "Invalid API key"}
{"ok": false, "error": "Usage limit reached. Upgrade at https://formfill.plenitudo.ai"}
{"ok": false, "error": "File not found: /Users/me/missing.pdf"}

---

Self-Hosting

git clone https://github.com/knportal/formfill-mcp.git
cd formfill-mcp

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
python manage_keys.py create --tier free
python server.py
# → MCP server running on http://localhost:8000

For remote agent access, deploy the included Cloudflare Worker (worker.js).

---

Architecture

server.py          — MCP server (3 tools)
auth.py            — API key validation + usage tracking (SQLite)
stripe_webhook.py  — Stripe subscription webhook handler
worker.js          — Cloudflare Worker (remote proxy)
manage_keys.py     — Key management CLI
data/keys.db       — API key store
data/usage.db      — Monthly usage counters

---

Troubleshooting

Values fill into the wrong fields Always call list_form_fields first. It returns each field's position (x, y on page). Use those coordinates — not guessed names — to identify fields. Higher y = higher on the page (PDF coordinates are bottom-up). This matters most for IRS/government PDFs that use hybrid XFA/AcroForm format.

"No fillable fields found" The PDF is either flat/scanned (no AcroForm layer), XFA-only (older Adobe LiveCycle format), or password-protected. The response includes pdf_type to tell you which. FormFill requires interactive AcroForm fields.

"None of the provided field names exist in this PDF" Field names were guessed rather than read from list_form_fields. The error response includes valid_fields — the correct names to use.

Claude Desktop: "not a valid MCP server configuration" Use command/args format (not url or type: streamableHttp). Include "--stdio" in args. Fully quit and reopen Claude Desktop after editing the config.

Server crashes: "Read-only file system: ./logs" Set FORMFILL_LOG_FILE to a writable path, or ensure FORMFILL_DATA_DIR points to a writable directory. The default ~/Library/Logs/formfill-mcp/server.log works without config on macOS.

API key limit reached Free tier: 50 fills/month. Upgrade at formfill.plenitudo.ai. Your key is upgraded automatically — no config change needed.

Check server health

• GET https://formfill.plenitudo.ai/health → {"status":"ok"}
• GET https://formfill.plenitudo.ai/smoke-test → fills a real PDF end-to-end, returns pass/fail per component

---

Contributing & Security

• CONTRIBUTING.md — dev setup and PR guidelines
• SECURITY.md — responsible disclosure policy

License

MIT — Copyright © 2025 Plenitudo AI

---

<div align="center"> <strong><a href="https://formfill.plenitudo.ai?ref=readme">formfill.plenitudo.ai</a></strong> · <a href="https://github.com/knportal/formfill-mcp/issues">Issues</a> · <a href="https://plenitudo.ai">Plenitudo.ai</a> </div>