TaxBrainAI MCP
8 offline Indian income-tax MCP tools: deterministic compute, regimes, citations, notices.
Open source Open in the app JSON README (API)
About
8 offline Indian income-tax MCP tools: deterministic compute, regimes, citations, notices.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- harshil-projects
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Last push
- 2026-07-06T00:59:07Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:56
- Updated
- 2026-08-29 03:02:56
- Origin id
io.github.harshil-projects/taxbrainai-mcp
README
# taxbrainai-mcp
A **standalone [MCP](https://modelcontextprotocol.io) 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`](https://github.com/harshil-projects/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](https://taxbrainai.harshilprojects.com) 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
```bash
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
```bash
# 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
```bash
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):
```json
{
"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:
```python
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](./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