Skip to main content
Glama

estv-mcp

CI

MCP server for the official Swiss federal tax administration calculator at 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

Related MCP server: Schwaizer BFS MCP Server

Install

uv sync

Register with Claude Code

From inside the repository:

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:

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

Development

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:

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.

Available Tools

13 tools
calculate_capital_payment_taxA

Tax on a lump-sum payout from pillar 2 or pillar 3a.

Capital withdrawals are taxed separately from ordinary income at a reduced rate, and the rate varies a lot between cantons. Pass a canton code, 'capitals' or 'switzerland' as location to rank places instead of computing a single figure.

Inputs: capital (required), location (required), age_at_payment (required), top, +7 more. Returns: object

calculate_company_taxA

Profit and capital tax for a company (GmbH, AG or similar).

Pass a canton code, 'capitals' or 'switzerland' as location to rank places, which is the usual reason to ask: cantonal profit tax rates for legal entities differ by a factor of roughly two across Switzerland.

Inputs: location (required), taxable_profit (required), taxable_capital (required), top, +8 more. Returns: object

calculate_inheritance_taxA

Inheritance and gift tax, which is cantonal and varies enormously.

Spouses and direct descendants are exempt in most cantons while unrelated beneficiaries and unmarried partners can pay a quarter of the estate, so the beneficiary relationship matters more than the amount. Omit beneficiary to see every relationship for one place, or pass a canton code, 'capitals' or 'switzerland' to rank places for one relationship.

Inputs: amount (required), location (required), top, is_gift, +3 more. Returns: object

calculate_taxA

Compute federal, cantonal, municipal and church tax for a household.

Uses ESTV's detailed model: it derives social-insurance contributions and standard deductions from the gross figures, so you only need income, wealth and family situation. Call list_deductions first if you want to supply pillar 3a, mortgage interest or other real deductions.

Inputs: income1 (required), location (required), age1, age2, +12 more. Returns: object

calculate_tax_from_taxable_amountsA

Apply the tax scales to amounts already known to be taxable.

Use this when the user reads figures off a tax assessment or return (steuerbares Einkommen / revenu imposable) instead of a gross salary. Note that cantonal and federal taxable income usually differ.

Inputs: location (required), taxable_income_federal (required), taxable_income_cantonal (required), language, +6 more. Returns: object

compare_locationsA

Rank municipalities by total tax burden for one and the same household.

Answers "where would I pay the least?". Scanning all of Switzerland covers ~2100 municipalities, so only the extremes plus summary statistics are returned; narrow with scope or only_cantons to see a specific region.

Inputs: income1 (required), top, age1, age2, +12 more. Returns: object

deduction_valueA

Measure what a deduction is actually worth to this household.

Sweeps a budget line (pillar 3a by default) and reports the tax saved at each level, plus the saving on each additional franc. Because rates are progressive the last franc of a deduction is worth more than the first, and the return flattens once a bracket boundary is crossed.

Inputs: income1 (required), location (required), age1, age2, +13 more. Returns: object

explain_tax_bracketsA

Show the statutory rate ladder and where an income sits in it.

Explains the number rather than just producing it: which bracket the household is in, the marginal rate there, and how far the next threshold is. The cantonal figure is the simple tax (einfache Staatssteuer), which the canton and municipality then multiply by their own rates.

The tax amount always comes from ESTV itself. The ladder is rebuilt from the published scale, which a few cantons express as a formula rather than a table; there the amount is still exact and ladder is simply absent.

Inputs: location (required), taxable_income (required), target, language, +3 more. Returns: object

find_cheapest_nearbyA

Rank municipalities within a radius of a point by tax burden.

The relocation question people actually ask: given that I have to stay within commuting distance of somewhere, where is the cheapest place to live? Pass the coordinates of the office or station and a radius.

Inputs: income1 (required), latitude (required), longitude (required), radius_km (required), +13 more. Returns: object

find_locationA

Resolve a place name or postal code to an ESTV tax location id.

Municipal tax multipliers differ inside a canton and sometimes inside a postal code, so every calculation is anchored on a tax_location_id.

Inputs: query (required), limit, language, tax_year. Returns: object

get_tax_yearsA

Report which tax years each ESTV calculator currently covers.

Inputs: no named parameters. Returns: object

list_deductionsA

Show the deduction/budget sheet ESTV derives for a household.

Returns every line item with the value ESTV assumes by default. Lines marked editable can be overridden through the deductions argument of calculate_tax (keyed by id), e.g. PRAEMIEN3A for pillar 3a contributions or SCHULDZINSEN for mortgage interest. Non-editable lines (gross salary, AHV/ALV/BVG contributions) are computed by the model.

Inputs: income1 (required), location (required), age1, age2, +10 more. Returns: object

plan_capital_withdrawalsA

Find the cheapest way to split a lump-sum withdrawal across tax years.

Capital payouts are taxed on a steeply progressive separate scale, so spreading a pension pot over several calendar years can save a large amount. Splitting within one year saves nothing: all payouts received in the same calendar year are added together before the rate is applied, and this tool models that. Read the caveats in the result before acting.

Inputs: location (required), first_year (required), total_capital (required), age_at_first_withdrawal (required), +9 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct tax calculation or query scenario. While `calculate_tax` and `calculate_tax_from_taxable_amounts` both compute tax, they differ in input types (gross vs taxable amounts). Similarly, `compare_locations` and `find_cheapest_nearby` both rank municipalities but one is global with optional filtering and the other is radius-based. Overall, descriptions clearly differentiate purposes, minimizing confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using lowercase with underscores (e.g., `find_location`, `calculate_tax`, `explain_tax_brackets`). The verbs are action-oriented (find, list, calculate, compare, get, plan, explain) and the nouns describe the domain entity. No mixing of conventions, making the pattern predictable.

    Tool Count5/5

    With 13 tools, the server covers the core Swiss tax calculation domain comprehensively without being bloated. Each tool serves a distinct purpose: location resolution, deduction listing, multiple tax computations (income, capital, inheritance, company), comparison utilities, planning, and bracket explanation. The count feels well-scoped for the complexity of the domain.

    Completeness5/5

    The tool set covers the full lifecycle of typical Swiss tax queries: resolving locations, understanding deductions, computing taxes from various inputs, comparing municipalities, optimizing capital withdrawals, and explaining brackets. Missing aspects like tax form filing or historical data are outside the server's stated purpose. The surface is complete for calculation and planning tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers