taxbrainai-mcp

A standalone MCP server exposing 8 tools for Indian personal income-tax work (ITR-1/2/3/4 + post-filing notices). It is built on FastMCP as a thin wrapper over the deterministic taxbrainai-compute engine plus a small statute graph that ships inside the package.

It runs fully offline with no API keys — every tool here is deterministic or an optional bring-your-own-index lookup. There is no LLM call anywhere in this package.

This is the extracted, self-contained MCP surface of the larger TaxBrainAI project. In the full product, three of these tools are backed by an LLM / vision model and a hosted case-law corpus; here those halves are replaced by deterministic equivalents (or made optional), so the package installs and starts with no private backend, no secrets, and no redistributed third-party data. See "Honesty about each tool" below.

The 8 tools

#	Tool	Kind	What it does
1	compute_tax	Deterministic — Decimal compute	Income-tax liability for a structured input (salary, capital gains, deductions, age, residency, regime). No LLM in the math path.
2	regime_compare	Deterministic — Decimal compute	Old vs new regime for the same inputs; recommends the cheaper, with savings delta + statutory citations.
3	simulate_scenario	Deterministic — Decimal compute	What-if: apply changes to a base input and compare tax before/after.
4	cite_section	Deterministic — statute graph	Resolves a section number to its title + a formatted citation, incl. the equivalent section in the other Act.
5	compare_acts	Deterministic — statute graph	Maps a section across IT Act 1961 ↔ IT Act 2025 via the equivalence graph.
6	classify_notice	Deterministic — table + pattern-match	Detects the notice section by pattern-matching the text, then returns curated section/type/deadline/guidance facts (not model-generated). Honest found: false when no known section is present.
7	reconcile_documents	Deterministic — diff	Flags cross-document mismatches across Form 16 / 26AS / AIS pre-extracted fields (PAN redacted in output). OCR/vision extraction is out of scope — bring your own extractor.
8	find_case_law	Optional — lexical BM25 retrieval	Lexical search over an optional case-law metadata index. No corpus ships with this package; set an env var to enable it (below), otherwise it returns an empty result set with a note.

Honesty about each tool

• Deterministic Decimal compute (1–3): all math flows through the property-tested taxbrainai-compute library (Hypothesis-verified, cross-checked against the official Income-Tax Dept ITR utilities). The server never authors a number.
• Deterministic statute graph (4–5): answered from a vendored snapshot of the 1961↔2025 statute graph (nodes.csv + edges.csv, shipped inside the package).
• Deterministic table / diff (6–7): in the full TaxBrainAI product these are LLM/vision-backed (a model reads the notice / extracts document fields). This standalone server keeps only the deterministic halves — a section/keyword matcher and a field-level reconciliation diff — so no model or key is required.
• Optional retrieval (8): find_case_law needs a case-law index, which is not bundled (third-party data is not redistributed here). It degrades gracefully to an empty result set unless you point it at your own index.

Install

pip install "taxbrainai-mcp[mcp]"     # server + FastMCP SDK
pip install taxbrainai-mcp            # tool library only (no SDK; importable + testable)

taxbrainai-compute is a hard dependency and is installed automatically.

Run

# installed console script
taxbrainai-mcp

# or the module form
python -m taxbrainai_mcp.server

FastMCP's run() serves stdio by default and also supports Streamable HTTP (build_mcp_server().run(transport="streamable-http")). No API keys are needed.

Optional: enable case-law search

export TAXBRAIN_MCP_CASELAW_INDEX=/path/to/caselaw.jsonl   # JSONL of {"title","court",...}

If your index is derived from Indian Kanoon (indiankanoon.org), attribute it accordingly.

Connect a client (Claude Desktop)

Add to claude_desktop_config.json (mcpServers block):

{
  "mcpServers": {
    "taxbrain": {
      "command": "taxbrainai-mcp"
    }
  }
}

If the console script is not on PATH, use "command": "python", "args": ["-m", "taxbrainai_mcp.server"].

Use the tools directly (no MCP SDK)

The tool logic is a plain class — handy for tests or embedding:

from taxbrainai_mcp import TaxBrainTools

t = TaxBrainTools()
print(t.compute_tax({"salary_income": 1275000, "regime": "new"})["total_tax"])  # 0 (rebated under Section 87A)
print(t.compare_acts("147")["equivalence"])

Registry manifest

server.json is the MCP-registry manifest (schema 2025-12-11), authored as a draft for submission. Its _meta block lists the exact pre-publish checklist (claim/publish the PyPI name, validate against the schema, authenticate the io.github.harshil-projects namespace). The package runs locally over stdio — there is no hosted remote endpoint.

Scope & disclaimer

Covers AY 2026-27 / FY 2025-26 for resident individuals / HUF (ITR-1/2/3/4). This is software for estimation, not tax, legal, or financial advice; verify against the official e-filing utility and a qualified professional before relying on any figure.

License

MIT — see LICENSE. Bundled statute graph data is derived from the text of the Income-tax Act (official statutory text). taxbrainai-compute is MIT-licensed.

---

mcp-name: io.github.harshil-projects/taxbrainai-mcp