# estv-mcp

[![CI](https://github.com/noaahh/estv-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/noaahh/estv-mcp/actions/workflows/ci.yml)

MCP server for the official Swiss federal tax administration calculator at
[swisstaxcalculator.estv.admin.ch](https://swisstaxcalculator.estv.admin.ch/).

It wraps the undocumented JSON API behind that SPA (no key, no auth) and exposes
income, wealth, lump-sum, inheritance and corporate tax figures for every Swiss
municipality and tax years 2010-2026.

## Tools

Household income and wealth:

| Tool | What it does |
| --- | --- |
| `find_location` | Postal code or place name to `tax_location_id` |
| `calculate_tax` | Federal, cantonal, municipal and church tax from gross income, wealth and family situation |
| `list_deductions` | The ESTV budget sheet with its default values, and which lines you may override |
| `calculate_tax_from_taxable_amounts` | Applies the tax scales to taxable income read off an assessment |
| `explain_tax_brackets` | The statutory rate ladder and where an income sits in it |

Comparing places:

| Tool | What it does |
| --- | --- |
| `compare_locations` | Ranks municipalities by total burden for the same household |
| `find_cheapest_nearby` | Same ranking, restricted to a radius around a point |

Planning:

| Tool | What it does |
| --- | --- |
| `plan_capital_withdrawals` | Cheapest way to split a pension lump sum across tax years |
| `deduction_value` | What a deduction is worth, franc by franc, at this income |

Other taxes:

| Tool | What it does |
| --- | --- |
| `calculate_capital_payment_tax` | Tax on a pillar 2 / pillar 3a lump-sum withdrawal, single place or ranked |
| `calculate_inheritance_tax` | Inheritance and gift tax by beneficiary relationship |
| `calculate_company_tax` | Profit and capital tax for a GmbH or AG |
| `get_tax_years` | Covered year range per calculator and the ESTV data version |

## Install

```sh
uv sync
```

## Register with Claude Code

From inside the repository:

```sh
claude mcp add estv-tax -- uv run --directory "$PWD" estv-mcp
```

Add `-s user` to make it available in every project rather than just this one.

Or in any MCP client config, with `/path/to/estv-mcp` replaced by wherever you
cloned it:

```json
{
  "mcpServers": {
    "estv-tax": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/estv-mcp", "estv-mcp"]
    }
  }
}
```

## Development

```sh
uv sync                            # install, including dev group
uv run pytest -q                   # tool-level tests plus golden values
uv run python scripts/stdio_smoke.py  # real MCP stdio handshake
uv run ruff check . && uv run ruff format --check .
```

Tests hit the live ESTV API, so they need network access but no credentials.
CI runs lint, the suite on Python 3.11/3.12/3.13, and the stdio smoke check on
every push and pull request, plus weekly on a schedule.

### Golden values

`tests/golden.json` pins recorded figures for a closed tax year, where the
scales should never move again. `tests/test_golden.py` re-checks them against
the live API with caching disabled, so the weekly run reports upstream drift as
a concrete diff rather than just confirming the endpoint still answers.

When a golden test fails, read the diff first. It usually means ESTV changed
something, not that this repo is broken. Once the change is understood:

```sh
uv run python scripts/update_golden.py   # prints every value that moved
```

### Caching

Responses are cached under `~/.cache/estv-mcp` for a week, which matters because
the planning tools fan out into dozens of sub-queries. `ESTV_MCP_NO_CACHE=1`
disables it, `ESTV_MCP_CACHE_DIR` and `ESTV_MCP_CACHE_TTL` override the
location and lifetime.

## Notes

- Amounts are CHF per year. `income_type='employed'` means gross salary; the
  model derives AHV/IV/EO, ALV, NBU and BVG contributions itself.
- Deduction overrides go through `deductions={id: value}` on `calculate_tax`,
  using the ids from `list_deductions` (`PRAEMIEN3A` pillar 3a, `SCHULDZINSEN`
  mortgage interest, `KKPRAEMIEN` health insurance premiums, `MIETAUSGABEN`
  rent, `KINDBETREUUNGSKOSTEN` childcare, and so on).
- `compare_locations(scope='switzerland')` covers ~2100 municipalities; only
  the extremes plus summary statistics come back so results stay readable.
- Church tax is only charged for `confession` values other than `none`.
- `plan_capital_withdrawals` models the rule that payouts received in the same
  calendar year are aggregated before the rate applies, so splitting within a
  year correctly shows no saving. It does not model the federal aggregation of
  a spouse's payouts, and years beyond ESTV's published range are priced with
  the latest available scales. Both are stated in the result's `caveats`.
- `explain_tax_brackets` always takes the amount from ESTV. The ladder is
  rebuilt from the published scale and reproduces ESTV exactly for the
  ZUERICH and BUND table layouts; splitting cantons apply extra rounding
  (flagged via `ladder_note`), and BL, FR, VD and VS publish formulas rather
  than tables, where the ladder is omitted rather than guessed at.
- Figures are the official ESTV model, not a binding assessment.

## API notes

Base URL: `https://swisstaxcalculator.estv.admin.ch/delegate/ost-integration/v1/lg-proxy/operation/c3b67379_ESTV`.
Every operation is a `POST` with a JSON body answering `{"response": ...}`. Bad
input returns an HTML 500 page rather than a structured error, which
`api.EstvClient` translates into an `EstvError`.

Enum values (from the SPA bundle):

- Relationship: single 1, married 2, concubinage 3, registered partnership 4
- Confession: reformed 1, roman catholic 2, christ catholic 3, none 4, other 5
- Income type: employed 1, self-employed 2, pensioner 3, other 4
- Language: de 1, fr 2, it 3, en 4
- `TaxGroupID`: cantons alphabetically 1-26 (AG=1 … ZH=26), capitals 88, all of Switzerland 99

Two gotchas worth recording:

- `API_exportManyTaxScales` reuses the same field names for two different
  layouts. In `ZUERICH` tables `Amount` is the width of a band; in `BUND`
  tables it is the lower threshold and `Taxes` carries the tax already due at
  it. Reading a `BUND` table with the `ZUERICH` rule gives a plausible but
  wrong number, so `TableType` has to be honoured.
- The geo search returns at most 200 results, silently clipping a large
  radius. `find_cheapest_nearby` detects the cap and says so.