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?

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.

Related MCP server: mcp-india-stack

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

Tools (v0.3)

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

Install

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"]
    }
  }
}

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."

Scope and limitations

Honest boundaries, so you know before you rely on it:

• Resident individuals, FY 2025-26 (AY 2026-27). NRI/RNOR computation differs (the form recommendation accounts for residency, the tax engine assumes resident).

• No filing. There is no public API to submit an ITR; only you or an authorized ERI can file. The agent prepares and verifies everything, then hands over.

• You supply the income figures. compute_tax computes tax on the heads you give it: salary, other income, 111A STCG, 112A LTCG, and old-regime deductions as a single total. It does not itself compute house property (30% standard deduction, 24(b) interest), other capital-gains heads (112 debt/property, 115BBH crypto, slab-rate debt MF under 50AA), or business P&L -- work those out separately, or with list_deductions for the Chapter VI-A caps, and pass the totals in.

• Not yet modeled: house property and business P&L computation (a presumptive flag exists, but only to pick the single-installment 234C schedule and to steer the form recommendation -- 44AD/44ADA income itself is not computed), crypto/VDA (115BBH), non-equity capital gains, loss set-off arithmetic (#4), Schedule FA valuation (#5), Form 16 PDF parsing (reconcile_documents takes Form 16 figures as input, it does not read the PDF), broker capital-gains statements (#7).

• Transaction-date rules not yet split. The engine applies FY 2025-26 rates uniformly; the 23-Jul-2024 capital-gains rate flip and the 1-Oct-2024 buyback change matter for FY 2024-25 returns, which this pack does not cover.

• The encrypted AIS file is not a safe place to store your data. Its password is your PAN plus your date of birth, stretched with only 1,000 PBKDF2-SHA256 iterations. Once someone knows your PAN, every plausible DOB can be tried in about 4 seconds single-threaded (measured on a laptop: 0.11 ms per key derivation over a ~36,600-date space). That is the portal's scheme, not this tool's choice, and nothing here can strengthen it -- treat a downloaded AIS export as effectively unencrypted and delete it when you are done.

• parse_ais decryption is unproven on a live export. The AIS password scheme is reverse-engineered from open-source utilities and verified against this repo's synthetic round-trip, never against a file the portal actually produced. If it fails, the error tells you to pass password explicitly or use the portal's CSV export, and an issue report with your download date helps fix it. Every other tool is unaffected.

• Not tax advice. Complex cases belong with a CA. Every output says so.

Design principles

• Local-only. stdio transport, no network calls, no telemetry, no accounts. Your documents are read from disk by this process and never uploaded anywhere. AIS decryption happens entirely on-device with Node's crypto -- the reverse-engineered password scheme has un-peppered fallbacks and an explicit password override in case the format rotates.

• What your MCP client still sees. Parsed output is returned to whatever client you connected, so if that client is a hosted LLM, the parsed contents reach that provider like any other message. PAN is masked in the human-readable text mirror, but the structuredContent payload carries the full parsed document (PAN, TANs, deductor names, amounts) because downstream tools need it. Local-only describes this server, not your whole stack -- for maximum privacy, run it against a local model.

• The LLM never does math. Every rupee is computed by pure functions over data/fy2025-26.json. 109 tests pin the engine to published worked examples and to statute: the 12L zero-tax case, the 12,10,000 marginal-relief case, the 12,70,588 relief exhaustion point on both sides, the surcharge bands with the First Schedule exclusion of capital-gains income, all three old-regime age bands, and the 234A/234B/234C/HRA/80GG golden cases.

• The agent drives, the engine decides. The interview sequencing is a prompt; every number and every form rule is deterministic code. Nothing is estimated.

• Year-parameterized. Rules live in per-FY JSON packs. FY 2026-27 (Budget 2026: Form 16 renamed to Form 130, 8 HRA metros, buyback reversion) lands as a new pack, not code changes.

• Not tax advice. Every tool that computes a rupee figure returns a disclaimers array and the fiscal year it applied; compute_tax, compute_hra and list_tax_years also return the exact rulePackVersion. Verify against the official utility before filing.

Roadmap

• v0.1 -- tax engine (both regimes + CG + surcharge + cess), regime comparison, advance tax, deduction checklist, 26AS text parser

• v0.2 -- parse_ais (encrypted AIS JSON, on-device decrypt), reconcile_documents (the #1-notice-trigger checks), 234B/234C interest with golden-case tests, HRA + 80GG calculators, old-regime 87A semantics fix

• v0.3 -- renamed to itr-agent; recommend_itr_form with loss-continuity awareness (#3), filing_checklist, the file_my_itr guided interview prompt

• v0.4 (priorities validated against a real AY 2026-27 filing) -- compute_loss_setoff (BFLA/CFL engine, #4), parse_form16 (TRACES PDF), broker capital-gains parsers -- Groww first, then Zerodha (#7)

• v0.5 -- compute_schedule_fa (foreign assets/RSU, Rule 115 rates, #5), portal quirks playbook (#6), mutual fund CAS via casparser, draft ITR JSON export, .mcpb one-click Claude Desktop bundle, MCP registry listing

Development

pnpm install
pnpm test          # vitest: engine golden files + in-memory MCP client tests
pnpm build
pnpm inspect       # MCP inspector against dist/index.js

Disclaimer

itr-agent is an open-source calculator, document parser, and filing guide. It is not a substitute for professional tax advice, and it never files anything -- output is meant to be verified against the official income tax utility, and the return is always submitted by you on the portal.

License

MIT