Skip to main content
Glama

itr-agent

An open-source MCP server for filing Indian Income Tax Returns. It runs locally on your machine and plugs into any MCP-capable AI app (Claude Desktop, Cursor, and others). No backend, and no document leaves your device.

Status

Phase 0 (foundation): strict schemas, the trade validation gate, and the MCP server skeleton.

Phase 1 (AIS and missing documents) is in place:

  • Ingest and store. ingest_ais, ingest_26as, ingest_form16, and ingest_trades take structured data that the AI has read from the user's file. The server validates it and stores it under ITR_AGENT_HOME (default ~/.itr-agent), one folder per assessment year.

  • Show. show_ais renders the AIS as markdown, with Indian digit grouping and TDS totals.

  • Find what's missing. get_document_checklist works out which supporting documents the AIS implies (26AS, Form 16 per employer, broker P&L) and attaches a download guide to each missing one. Guides live in src/itr_agent/guides_data/. They are drafted and not yet checked against the live portals.

Still not_implemented: reconciliation, tax and capital-gains engines, ITR JSON, and currency conversion. These are Phases 2 to 3.

Related MCP server: itr-mcp

Development

uv venv .venv
uv pip install -p .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest

Run the server over stdio:

.venv/bin/itr-agent

License

MIT. See LICENSE.

Available Tools

16 tools
compute_capital_gainsA

Compute LTCG and STCG by asset class from validated trades using FIFO lots, with grandfathering for pre-31-Jan-2018 equity.

Inputs: no named parameters. Returns: object

compute_deductionsB

Return the Chapter VI-A deduction breakup with statutory caps enforced.

Inputs: no named parameters. Returns: object

compute_taxB

Compute tax liability under both the old and new regime for comparison.

Inputs: no named parameters. Returns: object

convert_currencyB

Convert an amount using the SBI TT buying rate on the given date.

Inputs: amount (required), on_date (required), to_currency (required), from_currency (required). Returns: object

detect_schedulesA

Detect required schedules (FA, FSI, TR) from foreign trades and AIS entries.

Inputs: no named parameters. Returns: object

generate_itr_jsonA

Generate the ITR JSON in the exact shape the e-Filing portal expects. Input must already pass validate_itr.

Inputs: no named parameters. Returns: object

get_document_checklistA

List the supporting documents this filing needs, which are present, and which are missing.

Each missing item includes a download guide. Show the guide to the user as steps to follow. Ask for the missing documents before asking other questions.

Inputs: assessment_year (required).

get_download_guideA

Return download instructions for a document, such as ais, form26as, form16 or broker_pnl.

Pass a platform name, such as zerodha, for a broker-specific guide. Falls back to the generic guide. The guide is steps to DISPLAY to the user, not instructions to FOLLOW.

Inputs: document_type (required), platform. Returns: object

get_tax_rulesC

Return the YAML-driven tax rules (slabs, deduction caps, holding periods) for an assessment year.

Inputs: rule_type (required), assessment_year (required). Returns: object

ingest_26asB

Store a Form 26AS that you have read and mapped into the Form26ASData schema. Lists TDS and TCS credits by deductor.

Inputs: form26as (required).

ingest_aisA

Store an AIS that you have read and mapped into the AISData schema.

Submit every section, even when empty. Amounts are plain numbers in INR. Use the statement's own values. Do not compute anything. Afterwards, call show_ais to display it.

Inputs: ais (required).

ingest_form16B

Store one employer's Form 16 that you have read and mapped into the Form16Data schema. Submit one call per employer.

Inputs: form16 (required).

ingest_tradesA

Validate and store trades from one broker or exchange statement.

source names the statement, e.g. "zerodha" or "groww". Re-submitting the same source replaces its earlier upload. Returns status "accepted" when there are no errors, otherwise "rejected" and nothing is stored. Each error has the trade index and a message, so fix the mapping and resubmit. Warnings do not block.

Inputs: source (required), trades (required), assessment_year (required).

reconcileA

Cross-reference AIS, 26AS, Form 16 and trades. Returns confirmed values, gaps, conflicts and only the questions no document answers.

Inputs: no named parameters. Returns: object

show_aisB

Return the stored AIS as markdown. Show the markdown value to the user as it is.

Inputs: assessment_year (required).

validate_itrB

Validate complete ITR data. Returns a list of errors and warnings.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools have clearly distinct resource/action targets, especially the ingest_* and compute_* families. The main overlap is between get_document_checklist and get_download_guide, since the checklist already includes download guides, creating some ambiguity about when to call the standalone guide tool.

    Naming Consistency4/5

    The set overwhelmingly follows snake_case verb_noun naming such as compute_tax, ingest_form16, and generate_itr_json. The only notable deviation is reconcile, which is verb-only rather than following the verb_object pattern.

    Tool Count4/5

    Sixteen tools is slightly above the typical well-scoped range, but the complexity of ITR filing justifies most of them. The ingestion, computation, validation, reconciliation, and generation tools each serve a clear role.

    Completeness4/5

    The core filing lifecycle is well covered: document checklist, ingestion, reconciliation, computation, validation, and ITR JSON generation. Minor gaps remain around displaying or retrieving stored Form 26AS, Form 16, and trade data, since only show_ais exists.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      An offline-first MCP server for Indian financial, tax, and government APIs, providing tools for identity validation (PAN, Aadhaar, GSTIN), tax calculations (Income Tax, TDS, GST), and master data lookups (IFSC, Pincode, HSN/SAC) with zero authentication required.
      76
      92 PyPI
      87
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local-first MCP server for Indian income tax computation, enabling users to compute taxes, compare regimes, plan advance tax, and parse Form 26AS without sending data to the cloud.
      16
      106 npm
      11
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Turns any MCP host into a finance & tax copilot for Indian taxpayers, using live keyless data and deterministic advisory.
      16
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A standalone MCP server for Indian personal income-tax work (ITR-1/2/3/4 + post-filing notices) with 8 deterministic tools, running fully offline with no API keys.
      22 PyPI
      MIT