ArcaTax

Open-source, local-first US federal tax engine (Form 1040 + Schedules A, B, C, D, E and S-corp K-1 pass-throughs) that Claude drives over the Model Context Protocol. Claude interviews you and enters your documents; deterministic Python does all the math; the result can be written onto the official IRS Form 1040 PDF.

⚠️ Read this first

ArcaTax is not a CPA, enrolled agent, attorney, or tax software vendor, and nothing it produces is tax, legal, or financial advice. It is experimental, unaudited software. Tax law is intricate and several features (AMT, EITC, premium tax credit, education credits, foreign tax credit, state returns, the new 2025-2028 tips/overtime/auto-loan deductions, and more) are not modelled. The 2026 parameters were transcribed from IRS Rev. Proc. 2025-32 and statute, and items marked [UNV] in rules/2026/federal_1040.yaml were not independently verified. Have a qualified professional review any return before you file it. You alone are responsible for what you file. The software is provided "as is" under the license, with no warranty.

Privacy: all tax data stays on your machine in user_data/ and returns/, both git-ignored. ArcaTax has no telemetry, no cloud service, and does not store SSNs. The only network call it makes is an optional one-time download of the blank f1040.pdf from irs.gov. Caveat: when you chat with Claude, whatever you type or upload goes to Claude under your Anthropic account's terms. Local-first describes where ArcaTax stores data, not where the conversation goes.

Related MCP server: freelance-tax-mcp

Architecture

 You ── chat/upload ──► Claude (skills/tax-interview.md)
                           │  MCP tool calls (stdio)
                           ▼
   src/arcatax/mcp_server.py   FastMCP("ArcaTax")
        │            │              │
        ▼            ▼              ▼
   schema.py     engine.py      pdf_filler.py / txf_exporter.py
   Pydantic      pure, no LLM   pypdf → returns/2026_Form1040_Draft.pdf
   state JSON    math + gap     TXF   → returns/2026_return.txf
        │        questions
        ▼            ▲
 user_data/       rules/2026/federal_1040.yaml   (all IRS numbers; edit here, not in code)
 return_2026.json rules/2026/f1040_field_map.json (result key → PDF field)

Rounding follows the paper form (whole dollars, half up, rounded values carried forward), and income below $100,000 uses the IRS Tax Table midpoint method.

Quick start (non-technical users)

Full walkthrough with screenshots-in-words and troubleshooting: docs/INSTALL.md.

1. Install Python 3.11+ from python.org (Windows: tick Add python.exe to PATH).

2. Install ArcaTax: python3 -m pip install arcatax (Windows: py -m pip install arcatax).

3. Connect it to Claude Desktop: python3 -m arcatax.installer (Windows: py -m arcatax.installer), then fully quit and reopen Claude Desktop and say "Help me prepare my 2026 federal tax return with ArcaTax."

The setup tool backs up your Claude Desktop config and adds only the arcatax entry; your other servers are left untouched. Your data lives in ~/ArcaTax (override with --data-dir). --dry-run previews, --uninstall removes it.

Developer install

Requires Python 3.11+.

git clone <this repo> ArcaTax && cd ArcaTax
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m pytest

mcp is pinned <2 because 2.x renamed FastMCP.

Claude Desktop (manual configuration)

arcatax-setup does this for you. To do it by hand instead, edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), using absolute paths:

{
  "mcpServers": {
    "arcatax": {
      "command": "/absolute/path/to/ArcaTax/.venv/bin/arcatax-mcp",
      "args": [],
      "env": { "ARCATAX_HOME": "/absolute/path/to/ArcaTax" }
    }
  }
}

Restart Claude Desktop. ARCATAX_HOME is where user_data/, returns/ and templates/ live (defaults to the repo root in a source checkout, otherwise ~/ArcaTax). Claude Desktop starts servers with an arbitrary working directory, so set it explicitly. The interview procedure ships inside the server as the tax_interview prompt (and as server instructions), so no copy-pasting is needed.

Claude Code

claude mcp add arcatax --env ARCATAX_HOME=$PWD -- $PWD/.venv/bin/arcatax-mcp

Cowork / plugin

plugin.json (mirrored at .claude-plugin/plugin.json) registers the MCP server and the skill. Claude Code expects skills as skills/<name>/SKILL.md; if the flat skills/tax-interview.md is not picked up by your client version, move it to skills/tax-interview/SKILL.md.

The IRS PDF

.venv/bin/python -m arcatax.pdf_filler --download   # blank f1040.pdf → templates/irs_blank/
.venv/bin/python -m arcatax.pdf_filler --inspect    # list real field names + tooltips

IRS rewrites internal field ids every year, and its forms are XFA hybrids whose field descriptions ("1a. Total amount from Form(s) W-2...") live in the XFA template. The field map therefore matches on those descriptions unless you pin an exact field. It resolves all 37 mapped lines uniquely on the 2025 Form 1040, but has not been run against a 2026 form: the IRS was still serving the 2025 form when this was written. ArcaTax refuses to fill a form from the wrong year (it reports why instead of writing 2026 numbers onto 2025 lines). When the 2026 form appears, run --inspect, check the keys_unmatched list that export_filing_packet returns, and adjust rules/2026/f1040_field_map.json if lines were renumbered. Name, SSN, address and signature are intentionally left blank. ArcaTax does not e-file; use IRS Free File, commercial software, or a preparer.

Modelling notes and known gaps

• Single-year (2026), federal only. Filing status MFS assumes you lived with your spouse (no passive allowance).

• QBI: per-business W-2 wage/UBIA limits, SSTB phase-out, loss netting, REIT/PTP dividends, $400 minimum. Home-office, SE-deduction and retirement adjustments are allocated to businesses pro rata.

• Passive losses: simplified Form 8582 ($25k allowance with phase-out); suspended amounts are reported, not tracked.

• S-corp K-1: ordinary loss and distribution limits apply only if stock_basis_start_of_year is supplied.

• Capital gains: 0/15/20% only (no 25%/28% collectibles or unrecaptured §1250 rates).

• Itemized: SALT cap with high-income phase-down, 7.5% medical floor, 0.5% charity floor; the 37%-bracket limitation is flagged, not computed.

• Not computed: AMT, EITC, premium tax credit, education/foreign/energy credits, taxable Social Security, tips/overtime/car-loan deductions, estimated-tax penalty, state taxes.

Layout

rules/2026/        IRS parameters + PDF field map
src/arcatax/       schema, engine, pdf_filler, txf_exporter, mcp_server
skills/            tax-interview.md
templates/irs_blank/  blank IRS PDFs (the only PDFs git will track)
tests/             hand-checked 2026 scenarios
user_data/ returns/ tax_docs/   YOUR data (git-ignored)

License

See LICENSE.