⚠️ Disclaimer: This tool provides estimates for educational and informational purposes only. It does not constitute tax, legal, or financial advice. Always consult a qualified tax professional.

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 full legal notice.

Why This MCP?

Tax season is stressful. You're juggling W-2s, 1099s, deductions, credits, and trying to figure out if you should itemize or take the standard deduction. You Google "SALT deduction limit 2025" and get 10 conflicting articles.

This MCP server puts a tax-aware assistant inside your AI chat. Ask about a supported tax scenario in plain language and get deterministic estimates from versioned TY2024 through TY2026 data. Calculations run locally on your machine. No IRS login or SSN is required.

It includes OBBB provisions modeled for TY2025, federal brackets, selected credits and deductions, and explicitly supported state-tax paths. Unsupported state calculations fail closed instead of applying a rough top-rate estimate.

🔒 Privacy Architecture

⚡ Getting Started

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.

Step 2: Restart your AI assistant

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

Step 3: Start asking tax questions

That's it. Just chat naturally:

• "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 (44)

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. It performs no network requests, persistence, or telemetry. 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