FreeTaxUSA Server

An MCP server that lets AI agents file your taxes through FreeTaxUSA -- the free federal tax filing service.

Instead of paying $120+ for TurboTax's guided interview, this MCP gives any AI assistant (Claude, etc.) the ability to navigate FreeTaxUSA's interface, fill forms, check your refund, and walk you through filing -- conversationally.

Federal filing is free. State is $15.99. That's it.

---

How It Works

This is not an API wrapper. FreeTaxUSA has no public API.

This MCP uses Playwright to drive a real Chromium browser session against FreeTaxUSA's web interface. It reads forms via the accessibility tree, fills fields, navigates between sections, and returns structured data to the AI agent -- which then talks to you like a human tax preparer would.

You: "Here's my W-2, help me file"
        |
   [Claude / AI Agent]
        |
   [FreeTaxUSA MCP]  <-- this project
        |
   [Playwright + Chromium]
        |
   [freetaxusa.com]
        |
   [IRS e-file]

Features

• 15 tax filing tools across personal info, income, deductions, review, and filing
• Session persistence -- login once, cookies survive between invocations
• PII protection -- SSNs, account numbers, and EINs are automatically redacted from all tool outputs
• Dynamic navigation -- discovers FreeTaxUSA's section structure at runtime
• Anti-bot mitigations -- realistic viewport, disabled automation flags
• State paywall detection -- warns before triggering the $15.99 state filing purchase
• Prior year support -- configurable tax year for filing back taxes

Tools

Session Management

Tool	Description
authenticate	Log in. With Hermes configured, the session is brokered (no credentials needed). Otherwise pass email/password — used once, never stored.
get_session_status	Check if session is active, which tax year and section is loaded.

Page Interaction

Tool	Description
read_current_page	Read all form fields and their current values on the active page.
save_and_continue	Submit the current page and advance to the next.
navigate_section	Jump to a section by name ("income", "deductions") or SID number.

Personal Information

Tool	Description
fill_taxpayer_info	Fill name, SSN, DOB, occupation, and address.
fill_filing_status	Set filing status (single, married joint, head of household, etc.).

Tax Overview

Tool	Description
get_tax_summary	Get return overview: refund/owed, AGI, filing status, completed sections.
get_refund_estimate	Get current federal and state refund or amount owed.

Income (Phase 2)

Tool	Description
fill_w2_income	Enter W-2 wage and withholding data.
fill_1099_income	Enter 1099 income (INT, DIV, MISC, NEC, R, G, SSA).

Deductions, Review & Filing (Phase 3)

Tool	Description
fill_deductions	Enter standard or itemized deductions.
review_return	Run error check and get review results before filing.
file_extension	File Form 4868 for an automatic 6-month extension.
get_form_status	Get which sections are complete, incomplete, or have errors.

Phase 2 and 3 tools are stubbed and will be implemented in upcoming releases.

Quick Start

Prerequisites

• Node.js 20+
• A FreeTaxUSA account (free to create)

Install

git clone https://github.com/schwarztim/freetaxusa-mcp.git
cd freetaxusa-mcp
npm install
npm run build

Playwright will automatically install Chromium during npm install.

Configure

Add to your Claude Code MCP configuration (~/.claude/user-mcps.json):

{
  "mcpServers": {
    "freetaxusa": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/freetaxusa-mcp/dist/index.js"]
    }
  }
}

Or for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "freetaxusa": {
      "command": "node",
      "args": ["/path/to/freetaxusa-mcp/dist/index.js"]
    }
  }
}

Environment Variables

Variable	Default	Description
HERMES_URL	(unset)	Hermes broker URL. When set with HERMES_CLIENT_TOKEN, Hermes is the authoritative auth path — see Authentication via Hermes.
HERMES_CLIENT_TOKEN	(unset)	Bearer token for the Hermes broker (from ~/.hermes/client.token).
HERMES_SERVICE	freetaxusa	Service name registered with Hermes.
HERMES_SCHEME	cookie-session	Credential scheme to request from Hermes.
FREETAXUSA_LEGACY_AUTH	false	Opt back into the embedded Playwright login even when Hermes is configured-but-down. Default fails loudly on a broker outage.
FREETAXUSA_HEADLESS	true	Set to false to see the browser window
FREETAXUSA_USER_DATA_DIR	~/.freetaxusa-mcp/browser-profile/	Browser profile directory
FREETAXUSA_TAX_YEAR	2025	Tax year to file (change for prior years)

Authentication via Hermes

FreeTaxUSA has no API — authentication is a browser login session (cookies). By default this server drives an embedded Playwright login with the email/password you pass to the authenticate tool.

When the Hermes auth broker is configured, it becomes the authoritative auth path: Hermes performs the login on the host (handling SSO, MFA, captcha) and hands this server a fresh cookie session, which is injected into the browser context. In this mode the authenticate tool needs no email/password — just call it.

export HERMES_URL=http://127.0.0.1:9876
export HERMES_CLIENT_TOKEN="$(cat ~/.hermes/client.token)"
# optional overrides:
# export HERMES_SERVICE=freetaxusa
# export HERMES_SCHEME=cookie-session

Behavior:

• Hermes configured + reachable → cookie session brokered by Hermes; embedded login is skipped.
• Hermes configured + unreachable → authentication fails loudly (does not silently fall back to the embedded login). Set FREETAXUSA_LEGACY_AUTH=true to opt into the embedded fallback and supply email/password.
• Hermes not configured → embedded Playwright login as before (email/password required).

Operator setup required: this server becomes Hermes-capable in code, but runtime success depends on the operator registering FreeTaxUSA cookie-session credentials with the Hermes broker. Until that is done, set FREETAXUSA_LEGACY_AUTH=true (or leave Hermes unconfigured) to use the embedded login.

Use

Once configured, start a conversation with Claude:

You: I need to file my taxes. Log me in to FreeTaxUSA.

Claude: I'll authenticate you now. What's your FreeTaxUSA email and password?

You: email is [email protected], password is hunter2

Claude: [calls authenticate tool] You're logged in for tax year 2025.
        Let's start with your personal information. What's your full name?

You: John Smith, SSN 123-45-6789, born 01/15/1990

Claude: [calls fill_taxpayer_info] Done. Your address?

You: 123 Main St, Anytown PA 19301

Claude: [fills address, calls save_and_continue]
        Personal info is saved. Your current refund estimate is $2,847.
        Let's move to income. Do you have W-2s to enter?

Architecture

src/
  index.ts              # Entry point (stdio transport)
  server.ts             # MCP server + tool registration
  browser/
    context.ts          # Persistent browser context + async mutex
    navigation.ts       # SID-based navigation + dynamic discovery
    forms.ts            # Form reading/filling via accessible labels
  tools/
    session.ts          # authenticate, get_session_status
    overview.ts         # get_tax_summary, get_refund_estimate
    personal.ts         # fill_taxpayer_info, fill_filing_status
    income.ts           # fill_w2_income, fill_1099_income
    deductions.ts       # fill_deductions
    review.ts           # review_return
    filing.ts           # file_extension, get_form_status
    page.ts             # read_current_page, save_and_continue, navigate_section
  security/
    pii-filter.ts       # SSN/EIN/account number redaction
  types/
    tax.ts              # TypeScript interfaces
    sections.ts         # SID mapping + section aliases

Key Design Decisions

Accessibility tree over CSS selectors. Form elements are targeted by their accessible label (role + name), not by CSS class or ID. This survives UI redesigns that change styling but preserve semantics.

Dynamic SID discovery. FreeTaxUSA uses ?sid=N URL parameters for navigation. SID values can change between tax years. On first page load, the MCP scrapes navigation links to build a live SID map, with a static fallback.

PII filter on all outputs. Every string returned by every tool passes through filterPII() before reaching the MCP transport. SSNs are masked to ***-**-NNNN, EINs to **-***NNNN, and account numbers to ****NNNN. This protects against accidental PII exposure in AI conversation logs.

Single-page mutex. The browser has one active page. An async mutex serializes all tool calls to prevent race conditions from concurrent invocations.

Credentials never stored. Email and password are accepted as tool inputs, used to fill the login form, and discarded. The persistent browser context retains session cookies only. The profile directory is chmod 0700.

Security

This MCP handles sensitive financial data. The security model:

• PII redaction: All tool outputs are filtered. SSNs, EINs, and account numbers are automatically masked.
• No credential storage: Login credentials are provided per-call and never written to disk.
• Restricted browser profile: The session directory (~/.freetaxusa-mcp/browser-profile/) is created with 0700 permissions.
• State paywall guard: Navigation that would trigger a $15.99 purchase throws an error instead of proceeding.
• Session expiry detection: Every tool checks for redirect to the login page before acting.

Development

# Build
npm run build

# Run in development (auto-recompile)
npm run dev

# Run tests
npm test

# Watch tests
npm run test:watch

# Run with visible browser for debugging
FREETAXUSA_HEADLESS=false npm run start

Prior Year Filing

To file back taxes, set the tax year:

FREETAXUSA_TAX_YEAR=2024 node dist/index.js

FreeTaxUSA supports free federal filing for prior years. Note that prior year returns cannot be e-filed -- they must be printed and mailed.

Roadmap

• Phase 1: Session, navigation, personal info, tax summary
• Phase 2: W-2 and 1099 income entry
• Phase 3: Deductions, review, extension filing
• Phase 4: W-2/1099 PDF import via Claude vision, section walkthroughs
• Phase 5: Multi-year batch filing for back taxes

Disclaimer

This project is not affiliated with, endorsed by, or associated with FreeTaxUSA, TaxHawk Inc., or Intuit. FreeTaxUSA is a registered trademark of TaxHawk, Inc. Use of this tool is subject to FreeTaxUSA's Terms of Use. This tool automates a web browser -- the same actions a human would perform manually. You are responsible for the accuracy of your tax return.

License

MIT