itr-agent

Local-first ITR filing agent for Indian income tax. Claude interviews you one question at a time, picks your ITR form, computes your tax deterministically on your machine, reconciles your documents, and walks you to the portal's submit button -- no accounts, no uploads, no cloud.

Works with Claude Desktop, Claude Code, and any MCP client. Formerly published as itr-mcp.

You:    Help me file my ITR.
Claude: [file_my_itr] One question at a time. First: were you a resident of India
        for all of FY 2025-26?
You:    Yes, salaried, and I have vested US RSUs from my employer.
Claude: [recommend_itr_form] Foreign assets (Schedule FA) rule out ITR-1: you file
        ITR-2, due 2026-07-31. Next: how many employers this year?

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/demo-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="docs/demo-light.svg"> <img width="600" src="docs/demo-dark.svg" alt="Terminal animation of five tool calls against the built server. recommend_itr_form with foreign assets: ITR-2, due 2026-07-31, ITR-1 ruled out because foreign assets need Schedule FA. compare_regimes on 18L salary with 3.75L deductions: new Rs 1,50,800 vs old Rs 2,34,000, new saves Rs 83,200. compute_tax on 12.75L salary: Rs 0 after a Rs 60,000 rebate. The same salary plus 1.25L LTCG: Rs 62,400, because total income of Rs 13,25,000 loses the 87A rebate. schedule_advance_tax on 2.4L tax with 1.8L TDS: Jun Rs 9,000, Sep Rs 18,000, Dec Rs 18,000, Mar Rs 15,000."> </picture>

Those are the calls Claude makes during the interview, sent to the built server by scripts/demo.mjs. Every figure in the animation is one that run printed.

Why

Every Indian tax tool wants your data on their servers. itr-agent flips it: your documents stay local, the LLM never does arithmetic, and every number comes from a versioned rule pack you can audit. The agent layer drives the interview; the deterministic engine does the math.

What it will never do: submit the return for you. India has no public filing API -- returns are filed by you on incometax.gov.in (or by an authorized ERI/CA). The agent takes you to that button with every number verified; you press it.

The agent

file_my_itr (MCP prompt) runs the guided interview:

1. Residency, age band -- one question at a time
2. Income heads: salary, house property, capital gains, business/F&O, other sources
3. Disqualifier sweep: foreign RSUs/ESPP, director role, unlisted shares, ESOP deferral
4. Losses, current and brought-forward (they change the form)
5. recommend_itr_form -> the form, with rule-by-rule reasoning
6. compare_regimes -> the regime, with real numbers
7. parse_ais / parse_form26as / reconcile_documents -> fix mismatches BEFORE filing
8. schedule_advance_tax / compute_interest_234 if applicable
9. filing_checklist -> schedule-by-schedule portal walkthrough, ending at e-verification

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/filing-flow-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="docs/diagrams/filing-flow-light.svg"> <img width="880" src="docs/diagrams/filing-flow-light.svg" alt="The guided filing interview as a numbered flow. Step 1: you answer Claude one question at a time on residency, income and losses. Claude then calls the itr-agent tools in order: step 2 recommend_itr_form returns the form and deadline, step 3 compare_regimes returns the regime and savings, step 4 parse_form26as and parse_ais return your TDS rows, step 5 reconcile_documents returns the mismatches, step 6 schedule_advance_tax and compute_interest_234 return the installments, step 7 filing_checklist returns the portal walkthrough. Step 8, drawn dashed because it happens outside the tool: you e-verify and press submit on incometax.gov.in."> </picture>

Tools (v0.5)

| Tool | What it does | | --- | --- | | recommend_itr_form | ITR-1/2/3/4 selection with rule-by-rule reasoning and loss-continuity awareness: brought-forward business losses force ITR-3 even with zero current-year business income (Schedule CFL). Knows the AY 2026-27 two-house-property allowance, the s.194N bar, and the 44AD/44ADA turnover ceilings (when you pass the turnover). Returns each deadline with its statutory citation | | filing_checklist | Ordered, form-specific walkthrough: documents, reconciliation, computation, portal steps schedule by schedule, e-verification | | compute_tax | Full FY 2025-26 (AY 2026-27) computation: new/old regime slabs (incl. the senior and super-senior slab sets), standard deduction, employer NPS under 80CCD(2) in both regimes, house-property loss set-off (s.71(3A) cap; none under 115BAC), 87A rebate (new regime: Rs 60,000 where TOTAL income is up to Rs 12L with marginal relief, never offsetting 111A/112A tax; old regime: Rs 12,500 on total income up to Rs 5L, no marginal relief, offsets 111A), 111A (20%) / 112A (12.5% above 1.25L) capital gains with the unexhausted-basic-exemption set-off, surcharge with the 15% gains cap and its own marginal relief, 4% cess, s.288A/288B rounding | | compare_regimes | Old vs new side by side, recommended regime, savings amount | | schedule_advance_tax | Jun/Sep/Dec/Mar installment plan (15/45/75/100%) with shortfall tracking | | compute_interest_234 | Sections 234A/234B/234C interest with the statutory 12%/36% safe harbors, the s.234B(2) self-assessment payment ladder, and Rule 119A rounding (principal floored to Rs 100, part month = full month). Reports which sections it skipped and why | | compute_hra | HRA exemption per Rule 2A, period-wise (least of three limbs; FY 2025-26 metros: Delhi/Mumbai/Kolkata/Chennai) + the 80GG alternative, with its Rs 5,000-per-month cap and the bars under the new regime and alongside HRA | | list_deductions | Old-regime deduction checklist with statutory caps (80C, 80CCD(1B), 80D tiers, HRA metros) | | parse_form26as | Parse the caret-delimited Form 26AS Text export from TRACES into structured TDS entries with booking status (only F is creditable; the tool reports creditableTdsDeposited beside the raw total), and TCS rows separated into tcsEntries | | parse_ais | Decrypt + parse the AIS JSON export on-device (AES-256-CBC/PBKDF2 with the password derived from PAN + DOB); normalized rows with label-matched amounts/dates/codes | | reconcile_documents | Form 16 vs AIS vs 26AS mismatch report -- the checks that pre-empt 143(1)(a) intimations and 139(9) defect notices (TDS over-claim against the creditable 26AS total, non-final booking status, missing employer, undeclared AIS interest/dividend) | | list_tax_years | Supported fiscal years + AY 2026-27 filing deadlines with their statutory citations |

All tools are read-only (readOnlyHint: true), take zod-validated inputs, and return structuredContent alongside the human-readable text.

Install

What npx installs today. The npm badge at the top is live. While it reads 0.3.0, npx -y itr-agent installs the July 2026 engine without the 0.4.0 and 0.5.0 fixes (senior slab sets, surcharge marginal relief, s.87A on total income, 26AS booking status). No publish has reached npm since then: every npm publish from publish.yml has been refused by npmjs.com, most recently for v0.5.3 on 2026-10-20. Until the badge reads 0.5.x, use the .mcpb from the v0.5.3 release (one click, below) or install from source.

Claude Code

claude mcp add itr-agent -- npx -y itr-agent

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "itr-agent": {
      "command": "npx",
      "args": ["-y", "itr-agent"]
    }
  }
}

Claude Desktop, one click

From the v0.5.3 release on, every GitHub release carries itr-agent-<version>.mcpb and its .sha256. The bundle inlines the server and its dependencies into one file, so there is no npm or npx step: double-click it, or use Settings > Extensions > Install Extension in Claude Desktop. It needs Node 22 or later, like the npm package. pnpm bundle builds the same file locally into build/.

From source

git clone https://github.com/Sagargupta16/itr-agent
cd itr-agent
pnpm install
pnpm build
node dist/index.js   # stdio server

Migrating from itr-mcp

Same server, new name. Replace itr-mcp with itr-agent in your MCP config; the itr-mcp npm package is deprecated and frozen at v0.2.0.

Example prompts

• "Help me file my ITR." (starts the guided interview)
• "I'm salaried with US RSUs and 2L of equity LTCG -- which ITR form am I supposed to file?"
• "My CTC is 18L with 50K NPS through my employer -- which regime should I pick for FY 2025-26?"
• "My estimated tax is 2.4L and TDS covers 1.8L. Plan my advance tax installments."
• "Parse C:/tax/26AS.txt and total the TDS my employer deposited."

Filing after the due date

The s.139(1) due date for FY 2025-26 is in deadlines (list_tax_years prints them, with the statutory basis for each in deadlineCitations). Once it has passed, the return is belated under s.139(4) and four things change. file_my_itr asks about timing before anything else, because two of them are cheaper to know up front.

The pack's deadlines.itr1_2 is 2026-07-31 (s.139(1) Explanation 2(c)). deadlines.itr3_4_nonAudit is 2026-08-31: Finance Act 2026 moved non-audit assessees with business or professional income to 31 August from AY 2026-27, and CBDT granted no further extension (checked 2026-09-10). Audit cases are later again (deadlines.audit, 31 October), and no tool ever selects it because nothing here takes a 44AB input, so recommend_itr_form and filing_checklist both report the non-audit date and both say so in notes.

• You can still file, up to deadlines.belated (2026-12-31 for AY 2026-27) or before the assessment is completed, whichever is earlier.
• s.234F fee: Rs 5,000, or Rs 1,000 where total income does not exceed Rs 5 lakh. Both figures come from the rule pack (lateFee234F) and are returned by recommend_itr_form and filing_checklist.
• s.234A interest: 1% per month, or part of a month, on the tax still outstanding after TDS/TCS, advance tax and reliefs, running from the day after the due date to the date of filing. Call compute_interest_234 with monthsLateFiling (part month = full month, Rule 119A).
• s.80 forfeits this year's loss carry-forward. Business, speculative and capital losses of the current year cannot be carried forward in a belated return. Set-off of losses already determined in an earlier year survives, and so does the house-property loss carry-forward (s.71B). recommend_itr_form says this in notes whenever a business, speculative or capital loss flag is set, so its ITR-3 recommendation is not read as an unconditional carry-forward. A house-property-only loss does not trigger it, because s.71B carries that one forward either way.

Revising a filed return. Finance Act 2026 substituted s.139(5): a revised return may now be filed any time before the end of the AY (deadlines.revised, 2027-03-31), no longer three months before it. A revision filed after deadlines.revisedWithoutFee234I (2026-12-31) attracts the new s.234I fee; its tiers are not in the pack because no primary source for them was found, so read the amount off the portal.

Not mo