Irs Taxpayer

Estimates for planning and education only. Not tax, legal, or financial advice, and not filing software. See the legal notice.

Know the number before December 31

Should you convert $30,000 to Roth this year? Harvest gains in the 0% bracket? Top up your 401(k)? These decisions have deadlines, and a chatbot guess is not good enough when real money is on the line.

irs-taxpayer-mcp is a deterministic US individual tax engine for TY2024 through TY2026. It does the math from IRS annual tables, shows its work, and refuses to guess when a case is not supported.

• 🔒 Your numbers can stay on your machine. The direct CLI calculates locally, starts no MCP connection, calls no model, and sends no tax data anywhere.
• 🎯 Deterministic, not generated. The same inputs always give the same answer. A language model never does the arithmetic.
• 🛑 Fails closed. Unsupported states, years, or missing required facts return an error instead of a rough estimate.
• 🤖 Works with your AI assistant too. 45 MCP tools for Claude, Kiro, Cursor, and other MCP clients.

🚀 Try it in 30 seconds

npm install --global irs-taxpayer-mcpirs-taxpayer-mcp intake --output taxpayer-facts.json   # guided local questionnaireirs-taxpayer-mcp plan --facts taxpayer-facts.json

Example result for a synthetic TY2026 household (married filing jointly, $185,000 W-2, $12,000 long-term gains, two children):

# Local Tax Plan for TY2026
Adjusted gross income: $197,000Taxable income: $164,800Federal tax after refundable credits: $20,440Employee FICA: $14,122Total modeled tax: $34,562Take-home income: $162,438
## PrivacyCalculated directly by the local deterministic engine. No model, network request,persistence, or telemetry was used.

Add --json for structured output with assumptions, official sources, a calculation trace, and privacy.modelInvoked: false.

💡 Decisions it helps with

🔒 Privacy Architecture

⚡ Getting Started

Option A: Direct local mode (recommended for taxpayer facts)

Install once, before entering any tax facts:

npm install --global irs-taxpayer-mcp

Run the guided local questionnaire. It does not start MCP or invoke a model:

irs-taxpayer-mcp intake --output taxpayer-facts.json

Or create and edit a strict local template:

irs-taxpayer-mcp template --output taxpayer-facts.jsonirs-taxpayer-mcp validate --facts taxpayer-facts.json

Calculate directly through the deterministic engine:

irs-taxpayer-mcp plan --facts taxpayer-facts.jsonirs-taxpayer-mcp plan --facts taxpayer-facts.json --json

New facts files are created with mode 0600 on POSIX. On Windows, the CLI rejects existing symbolic links but relies on the current user's filesystem permissions. Existing files are not replaced unless --force is explicit. Imported JSON is limited to 1 MiB, rejects symbolic links and unknown fields, and does not accept names, SSNs, addresses, employer IDs, or account numbers.

Using npx may download the public package before execution, but the direct commands do not send the facts file or its values over the network.

Option B: MCP mode for AI assistants

The MCP server makes no network requests and stores no taxpayer data. However, facts typed into an MCP client may be processed by that client's model provider. Use direct local mode or a local-model MCP client when end-to-end local handling is required.

MCP Step 1: Add to your AI assistant

Add this to your MCP client configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{  "mcpServers": {    "irs-taxpayer": {      "command": "npx",      "args": ["-y", "irs-taxpayer-mcp"]    }  }}

Kiro (.kiro/settings/mcp.json):

{  "mcpServers": {    "irs-taxpayer": {      "command": "npx",      "args": ["-y", "irs-taxpayer-mcp"]    }  }}

Cursor: same format in Cursor's MCP settings.

MCP Step 2: Restart your AI assistant

After saving the config, restart the app. The MCP server will auto-download and connect.

MCP Step 3: Ask supported tax questions

The client model converts natural language into tool arguments. Do not enter real taxpayer facts here unless the selected MCP host and model satisfy your privacy requirements:

• "Calculate my federal tax: $150k income, married filing jointly, 2 kids"
• "Compare California vs Texas vs Washington for $200k income"
• "I'm a freelancer making $80k: what are my quarterly estimated taxes?"
• "What tax credits am I eligible for? AGI $60k, single, one child"
• "Should I itemize or take the standard deduction? I pay $15k in mortgage interest and $12k in state taxes"
• "Explain the Backdoor Roth IRA strategy"
• "How much is the EITC for a family of 4 earning $35k?"
• "I exercised ISOs this year: will I owe AMT?"
• "Help me plan my year-end tax moves. I have a 401k and HSA."

Alternative: Docker

docker build -t irs-taxpayer-mcp .docker run -i irs-taxpayer-mcp

Alternative: Streamable HTTP Transport

npx irs-taxpayer-mcp --http --port 3000# MCP endpoint: http://127.0.0.1:3000/mcp# Health check: http://127.0.0.1:3000/health

HTTP mode is stateless and binds only to a loopback host by default. Browser requests must use an exact allowed Origin. Add a trusted browser Origin with a repeatable flag:

npx irs-taxpayer-mcp --http \  --allowed-origin https://trusted-client.example

The legacy --sse flag remains a deprecated alias for --http. The old /sse and /messages endpoints are not exposed.

🛠️ Tools (45)

All tools use the current MCP registerTool API. Each advertises read-only annotations and an output schema, and returns both human-readable text and structuredContent. Error results include a stable error code, message, and recovery suggestion.

The 1.0 flagship generate_tax_plan workflow returns domain structured results, assumptions, official source provenance, a calculation trace, and explicit unsupported boundaries. The deterministic engine performs no network requests, persistence, or telemetry. Its structured privacy metadata reports whether the MCP adapter or direct CLI path was used. Unsupported tax years, state profiles, and required worksheet facts fail closed. See Local Tax Planner 1.0 Contract.

Federal Tax Calculations

Deduction Analysis

Tax Credits

Retirement & Strategy

Tax Planning & Scenarios

State Taxes

IRS Information

OBBB Act (2025) Tools

Full Reports & Analysis

Guidance & Feedback

📊 Tax Year Coverage

TY2024

Supported historical calculation year using IRS Revenue Procedure 2023-34. Standard deduction $14,600 (single) / $29,200 (MFJ). CTC $2,000. SALT cap $10,000.

TY2025

Reflects OBBB signed July 4, 2025:

• Standard deduction: $15,750 (single) / $31,500 (MFJ) / $23,625 (HoH)
• Child Tax Credit: $2,200 per child (up from $2,000)
• SALT cap: $40,000 for AGI ≤ $500K (was $10,000)
• New deductions: tips ($25K), overtime ($12.5K), senior bonus ($6K age 65+), auto loan interest ($10K)
• 401k catch-up: $11,250 for ages 60-63 (SECURE 2.0)

TY2026

Uses IRS Revenue Procedure 2025-32 and the SSA 2026 contribution and benefit base:

• Standard deduction: $16,100 (single) / $32,200 (MFJ) / $24,150 (HoH)
• Child Tax Credit: $2,200 per qualifying child, with up to $1,700 refundable
• SALT cap: $40,400 for MAGI up to $505,000; $20,200 and $252,500 for MFS
• Social Security wage base: $184,500
• AMT exemption phase-out at 50% above $500,000 / $1,000,000 AMTI (OBBB)
• Non-itemizer charitable deduction ($1,000 / $2,000), 0.5% itemized charitable floor, and 2/37 itemized deduction limit
• Child and Dependent Care Credit up to 50% of qualifying expenses
• 401(k) $24,500, IRA $7,500, HSA $4,400 / $8,750
• Updated ordinary, capital-gains, EITC, and AMT thresholds

Supported Scope and Boundaries

This project is a deterministic estimation and planning engine, not tax preparation or filing software.

• Federal estimates cover the modeled TY2024 through TY2026 inputs exposed by each tool. They do not implement every Form 1040 line, schedule, election, limitation, carryforward, or dependency rule.
• State reference information covers all 50 states and DC. Numeric estimates require an exact tax-year profile: TY2024 supports AK, CA, FL, NV, SD, TN, TX, and WY; TY2025 supports AK, FL, NH, NV, SD, TN, TX, and WY; TY2026 supports those states plus CA, GA, IL, IN, KS, KY, MA, MI, MN, MS, NC, ND, NE, NJ, OH, PA, RI, and VA. City, county, and school district income taxes (IN, KY, MI, OH, PA) are not included. Rhode Island income above $261,000 and Minnesota AGI above $220,650 return an error because their deduction phase-outs are not modeled. California supports single and married brackets only (HoH Schedule Z is not modeled). Other state-year and filing-status paths return an error.
• State calculations do not yet model part-year or nonresident allocation, every local tax, or separate HoH and MFS brackets.
• QBI, AMT, audit-risk, retirement, relocation, and multi-year outputs are planning estimates with documented simplifications.
• Refund projections depend only on the inputs and refundable credits modeled by the selected tool. They are not an IRS refund determination.
• The server does not generate a tax return, sign a return, transmit MeF data, or provide filing eligibility validation.

See ROADMAP.md for the remaining work toward a filing-grade federal return engine.

🧮 Calculation Engine

Numeric regression tests cite IRS Revenue Procedures, IRC sections, and relevant legislation. Reference and planning tools may summarize rules that are not fully represented in the calculation engine.

🏗️ Build from Source

Requires Node.js 20 or later.

git clone https://github.com/dma9527/irs-taxpayer-mcp.gitcd irs-taxpayer-mcpnpm installnpm run buildnpm start          # stdio modenpm run dev        # development mode (tsx)

🐛 Found a Bug?

• Calculation error or incorrect data? Open an issue: include the tool name, tax year, a rounded or synthetic example, and the expected result. Do not post taxpayer PII.
• Planner use case or product gap? Use the Planner Feedback form. Do not include taxpayer PII or a real tax return.
• Questions or discussion? GitHub Discussions
• Want to contribute? See CONTRIBUTING.md

🤝 Contributing

Contributions welcome. Please ensure:

• All tests pass (npm test)
• Build succeeds (npm run build)
• No any types in TypeScript
• Data changes include IRS source citations

See CONTRIBUTING.md for full guidelines.

Legal Notice

This software is provided "as is" without warranty of any kind. The authors and contributors are not tax professionals, CPAs, enrolled agents, or attorneys. No attorney-client, CPA-client, or fiduciary relationship is created by using this software. Tax laws change frequently and vary by jurisdiction. The calculations may contain errors, omissions, or may not reflect the most recent legislative changes. You are solely responsible for your tax filing decisions. The authors disclaim all liability for any damages arising from the use of this software. See DISCLAIMER.md for the full legal notice.

📄 License

MIT