taxtrace
This MCP server lets an AI assistant inspect a taxtrace workspace in a read-only, masked form.
Get workspace status: tax years, document counts, how many were read, saved files by kind, and whether a to-do list exists.
List documents with stable IDs, masked folder/file names, file kind, and read/unread status; filter by all, read, or unread.
Inspect a document’s page outline with masked first lines to identify forms/worksheets, with pagination; locked PDFs are reported but not opened.
Check 1098, 1099, or K-1 forms across PDFs or for one document: page, tax year, pass/fail counts, failed checks, and open questions without exposing values.
View open to-dos from todo.md: due date, days left, grouping, and masked text/notes/subtasks; filter by upcoming days.
All actions are read-only, idempotent, non-destructive, and return masked data only; nothing is changed, filed, or calculated.
Integrates with the macOS Keychain to store and retrieve passwords for encrypted PDFs, with per-read approval via Touch ID or Apple Watch through a compiled helper.
taxtrace
Prepare a US federal and state return from your own documents, on your own machine, with every number traced to the page it came from.

taxtrace does not file anything. You point it at a folder of your documents (W-2s, 1099s, 1098 mortgage statements, partnership K-1s, property manager statements, foreign bank statements, last year's return). It reads them and writes an entry sheet to type into consumer tax software, an FBAR (foreign bank account report) account list, and a list of questions for you: anything it could not settle from the documents alone.
Three rules hold everywhere:
Nothing is guessed. Every value carries the file, the page and the exact text it was read from, and a check rejects a value whose text is not on that page.
Your documents never leave your machine. Reading them is plain code and text recognition, not an AI model; the only model that sees your real values is a local one on your Mac (Apple's MLX, for example). The optional chat can use a cloud model, which only ever sees masked text: digits become
#, and words outside the IRS's own vocabulary become*.Nothing is decided silently. A receipt that could be a repair or an improvement, a missing 1099, a rate choice: each is a question with the evidence next to it.
What the demo shows
The two-minute demo uses made-up documents only: it opens taxtrace in the browser on a household's workspace (the to-do list, the tax-saving moves), imports a second batch of documents on the Import screen, shows the Entry sheet screen with each value's document and page, then the chat, what a cloud model is sent, and a question with an amount in it staying on the Mac. Every video is filmed in the page, never in a terminal. Every value arrives with its source and a status: ready, estimate or missing. Illustrative output for an invented Initech employee in Boulder, CO, with round figures:
Entry sheet line | Value | Status | Read from |
Wages (W-2 box 1) | 120,000 | ready |
|
Federal tax withheld (box 2) | 20,000 | ready |
|
Mortgage interest (1098 box 1) | 9,000 | ready |
|
Dividends (1099-DIV box 1a) | 1,500 | estimate |
|
Estimated tax payments | missing | run |
The real sheet is a plain text file, entry/<year>.txt, with one such row per line. The terminal shows counts and pass/fail results, never amounts.
Related MCP server: obsify
How well does it work
More than 500 tests (pytest), run by CI on Python 3.10 and 3.13. Every fixture is invented, and a test builds a workspace full of made-up amounts and names and checks that none of them appear in any MCP tool's output. This is not a measured accuracy rate against real returns. A filed return, when you have one, is the cross-check: agi, tax and d400 compare each line with it and say which way and roughly how far it differs.
Install
taxtrace needs Python 3.10 or newer. uv brings its own Python, so install uv first, then taxtrace:
curl -LsSf https://astral.sh/uv/install.sh | sh # installs uv (or: brew install uv)
uv tool install taxtraceAlready have Python? pipx install taxtrace works too. Extras: taxtrace[chat] (cloud chat), taxtrace[mcp] (MCP server).
Use
taxtrace import ~/Downloads/portal-export.zip # sort a preparer's export into ~/TaxData by tax year
taxtrace prior # carryforwards from last year's filed return
taxtrace k1 2026 # every K-1 in the 2026 folder
taxtrace w2 "2026 W-2 Initech.pdf" # a W-2, every box
taxtrace entry --year 2026 # the entry sheet, plus what is still to come
taxtrace agi --year 2026 # adjusted gross income, against the filed return if any
taxtrace ui # the workspace and a chat in the browser
taxtrace --help # every commandStart by putting your documents in a workspace folder, one subfolder per tax year (~/TaxData/2026, or under $TAXTRACE_HOME): import does that for a preparer's export, or copy the files in yourself. taxtrace refuses to place the workspace inside a git repository.
Limits
Not tax advice, and not a filing tool: you type the entry sheet into your own tax software, and a preparer should review the result.
Federal tax tables are built in for 2025 and 2026, for single and joint returns. The alternative minimum tax and Form 8995-A (the long form of the business-income deduction) are not worked out, and the output says so.
The only state return is North Carolina's Form D-400 (full-year residents).
Readers are written for the layouts seen so far: printouts from Drake (a tax preparer's software), common broker and lender forms, and some Indian bank statements. An unfamiliar layout becomes a question, not a guess.
macOS is the best-supported system: the Keychain password handling (for locked PDFs), the always-on service and local MLX models are macOS only.
Local-only: nothing is sent anywhere unless you turn on the chat's cloud models, and those see masked text. The only other outside lookup is public exchange rates for foreign amounts (a currency and a date, nothing about you). The MCP server (the way an AI assistant such as Claude calls taxtrace's tools) returns masked text only and is read-only.
Documentation
Everything else is in docs, one page per topic:
Commands: every command in one line each
Install, workspace and documents: import, OCR, locked PDFs, the Keychain
Planning: estimated tax, IRAs, a job change, stock sales
The return: entry sheet, AGI, total tax, North Carolina
Foreign side: India's return, bank statements, FBAR, Form 1116
Chat and the MCP server and agent skill: masked, read-only views of your workspace for Claude or another AI assistant (MCP is the protocol they use to call tools)
Support and listings
If taxtrace helps with your return, a ⭐ on GitHub is how I know: taxtrace has no usage tracking, so stars are the only count of who uses it. If it saved you a preparer's fee, a $1 coffee says so too.
MIT licensed.
Available Tools
5 toolsget_document_outlineARead-onlyIdempotent
A document's pages, each with its first lines masked: which forms and worksheets it holds, and in what order. A password-protected document is reported as locked, not opened (taxtrace's own commands read it with a password from the Keychain). To see how the forms in it checked out use get_form_checks; to find the id, list_documents.
Inputs: id (required), limit, lines, start.
get_form_checksARead-onlyIdempotent
Read the forms of one kind in the workspace's PDFs and report how their checks came out, never a value: per form its document id, page, tax year, how many checks passed of how many, the ones that failed and the questions it leaves the person (box names and masked quotes). Every value taxtrace reads is traced to its page and rejected if its text isn't there, so a failed check means a value to look at by hand. Locked documents are skipped and counted. For a document's other pages use get_document_outline.
Inputs: form (required), id.
get_statusARead-onlyIdempotent
What the person's workspace holds, as counts: tax years (folders named for one), each folder's number of documents, how many documents taxtrace has read, how many files it saved per kind of reading, and whether a to-do list exists. Names are masked. Start here; for the documents themselves use list_documents, for the to-dos use get_todo.
Inputs: no named parameters.
get_todoARead-onlyIdempotent
The person's open money and tax to-dos from todo.md in their workspace, soonest first: section, due date, days left, group (overdue, today, week, later, undated), and the text, notes and sub-tasks masked (the dates are real; the wording is masked, so ask the person what an item says if it matters). Nothing is changed: the person ticks items on the taxtrace page. For the documents use list_documents.
Inputs: days.
list_documentsARead-onlyIdempotent
The workspace's documents, each with an id, its folder and file name (masked), its kind (pdf, csv, ...) and whether it was read. Nothing is opened, so no password is asked for. The id is what get_document_outline and get_form_checks take. For counts only use get_status.
Inputs: only.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct resource and action: workspace counts, document inventory, per-document outline, form-check results, and to-dos. Descriptions explicitly point to sibling tools for adjacent needs, so an agent can tell which tool to use.
All tool names are snake_case verb_noun forms: list_documents, get_status, get_todo, get_document_outline, get_form_checks. The get_/list_ distinction is used consistently for retrieval style.
Five tools are well-scoped for a read-only tax workspace inspection server. Each tool covers a distinct layer of the workspace and none appears redundant.
The surface covers workspace overview, document listing, per-document outline, form-check results, and to-do retrieval. The read-only design is intentional, though there is no direct document-content or search tool for deeper inspection.
Maintenance
Related MCP Connectors
Read-only US tax reference for notices, deadlines, filing screens, and clearly labeled estimates.
Read-only finance and operations controls for AI agents with evidence and safe next actions.
See Luca close a month of AI spend and agent payments, with evidence. Read-only, no key.
View client requests, prepare actions and approve work within your firm's permissions.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceStreamlines tax professional workflows by automating conversational client intake and generating personalized document checklists based on specific tax situations. It includes tools for calculating case complexity and routing clients to appropriate specialists to optimize appointment throughput.-
- AlicenseAqualityCmaintenanceLets AI assistants work on sensitive files by reasoning over schemas and masked output while deterministic local code handles raw data, never exposing real values to the model.531 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceChecks a US company's federal and state filing obligations and searches the user's own documents for evidence, sending only structured facts so files never leave the machine.4MIT
- FlicenseNot gradedqualityBmaintenanceEnables agents to audit bank transactions and receipts against IRS Schedule C expense categories, calculate deductible amounts and estimated tax savings, and surface audit-risk flags.7-