taxfill-mcp

Your AI assistant prepares a paper U.S. tax return: taxfill fills the official PDFs, verifies every number, and tells you exactly how to sign and mail it.

[!WARNING]
taxfill-mcp is not tax advice and not a tax preparer. Everything it produces is a review draft: you check
every number, sign every form, and file the return yourself. It does not e-file (paper print-and-mail, by design).
MIT licensed, provided as-is with no warranty.

What it does

The AI interviews and reasons with you; taxfill does the arithmetic, PDF field mechanics, consistency checks and filing logistics.

• Guided interview to filled forms. Your MCP agent (Claude Code, Claude Desktop/Cowork, Copilot, Codex CLI) asks
  the right questions, reads your W-2s and 1099s, and fills the official IRS and state PDFs. Unknown values stay blank; nothing is invented.
• Math you don't have to trust an LLM for. Every number comes from a deterministic calc engine over cited, per-year
  tax data and is recomputed independently at verify time. The mandatory verify gate checks math, cross-form consistency, clipped text, and every rendered page.
• The last mile, done. A plain-language bottom line, then a personal pay / print / sign / mail checklist.
• Private and free. taxfill runs on your computer and sends nothing about you anywhere: no cloud, no accounts, no
  telemetry. Its only download is blank forms from the tax agencies' own sites (or an exact Internet Archive copy when a state
  site blocks scripts), checksum-verified for a form with a pack (a form with no pack has its checksum recorded, not
  pinned). Your AI assistant does see the documents and answers you give it, under its provider's data policy; taxfill
  masks SSN-shaped values in its own error messages.

Quickstart

Pre-release: runs from a source checkout. It is not on PyPI yet, so uvx taxfill-mcp and the one-click
.mcpb bundle are not available yet. Known gaps: FAQ.

You need uv (it installs Python for you) and git.

git clone https://github.com/Ryanczj0306/taxfill-mcp
cd taxfill-mcp
uv sync                 # creates the venv, installs both packages
uv run taxfill tools    # smoke test: lists every tool (your agent starts the server itself)

Then connect your agent, using the absolute path to the checkout, and install the workflow skill so the agent
follows taxfill's rules (you confirm every value before filling; the verify gate is mandatory):

• Claude Code — add the server for every project, then install the skill:

  claude mcp add --scope user taxfill -- uv run --project /ABSOLUTE/PATH/TO/taxfill-mcp taxfill-mcp
  mkdir -p ~/.claude/skills/taxfill && cp skills/claude/SKILL.md ~/.claude/skills/taxfill/
  

• Claude Desktop / Cowork — merge this into the mcpServers object of claude_desktop_config.json (Settings →
  Developer → Edit Config) and restart the app; then, with code execution enabled, upload a ZIP of the skills/claude
  folder as a skill (how):

  { "mcpServers": { "taxfill": {
      "command": "uv",
      "args": ["run", "--project", "/ABSOLUTE/PATH/TO/taxfill-mcp", "taxfill-mcp"] } } }
  

• Codex CLI / Copilot — put the same uv run … taxfill-mcp command in their MCP config, and copy the matching
  instructions where the agent reads them: skills/codex/AGENTS.md into the folder you run
  Codex from (or ~/.codex/AGENTS.md), or skills/copilot/instructions.md to
  .github/copilot-instructions.md in your workspace.

Then ask your agent: "Help me prepare my 2025 federal return." Filling in the
intake worksheet first makes the interview faster.

Tools not showing up? Check that the path is absolute and fully restart the client; if Claude Desktop reports
spawn uv ENOENT, set "command" to the full path printed by which uv. More: troubleshooting.

How a session works

INTAKE → EXTRACT & CONFIRM → ESTIMATE & ROADMAP → RESIDENCY & SCOPE → POSITIONS → FILL → VERIFY → SUMMARY → FILE & PAY

You confirm every extracted value before filling and approve the summary before printing. Each position you take is
recorded with its authority in RECONCILIATION.md, your audit trail. Progress is saved in a local workspace
(~/taxfill-workspace/<year>/), so you can resume days later.

What it covers

Most TY2026 forms are mapped from the IRS early-release drafts and fill in rehearsal mode only until the final forms
post (the 2026 Form 1040-ES vouchers are final).
Full form-by-year matrix: docs/COVERAGE.md.

Read more

Repo layout: packages/core (pure-Python engine) · packages/mcp-server (thin MCP wrapper plus the taxfill CLI) ·
formpacks/ (per-form field maps as YAML) · knowledge/ (per-year tax law as cited YAML) · skills/ (agent instructions) ·
scripts/ (maintainer tooling). Coverage grows by adding data packs, not engine code; blank PDFs are fetched at runtime, never stored here.

License

MIT. Provided as-is, with no warranty. Not tax advice; you review, sign and file your own return.