estv-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@estv-mcp calculate income tax for Zurich 2024"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
estv-mcp
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 |
| Postal code or place name to |
| Federal, cantonal, municipal and church tax from gross income, wealth and family situation |
| The ESTV budget sheet with its default values, and which lines you may override |
| Applies the tax scales to taxable income read off an assessment |
| The statutory rate ladder and where an income sits in it |
Comparing places:
Tool | What it does |
| Ranks municipalities by total burden for the same household |
| Same ranking, restricted to a radius around a point |
Planning:
Tool | What it does |
| Cheapest way to split a pension lump sum across tax years |
| What a deduction is worth, franc by franc, at this income |
Other taxes:
Tool | What it does |
| Tax on a pillar 2 / pillar 3a lump-sum withdrawal, single place or ranked |
| Inheritance and gift tax by beneficiary relationship |
| Profit and capital tax for a GmbH or AG |
| Covered year range per calculator and the ESTV data version |
Related MCP server: Schwaizer BFS MCP Server
Install
uv syncRegister with Claude Code
From inside the repository:
claude mcp add estv-tax -- uv run --directory "$PWD" estv-mcpAdd -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 movedCaching
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}oncalculate_tax, using the ids fromlist_deductions(PRAEMIEN3Apillar 3a,SCHULDZINSENmortgage interest,KKPRAEMIENhealth insurance premiums,MIETAUSGABENrent,KINDBETREUUNGSKOSTENchildcare, 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
confessionvalues other thannone.plan_capital_withdrawalsmodels 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'scaveats.explain_tax_bracketsalways 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 vialadder_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_exportManyTaxScalesreuses the same field names for two different layouts. InZUERICHtablesAmountis the width of a band; inBUNDtables it is the lower threshold andTaxescarries the tax already due at it. Reading aBUNDtable with theZUERICHrule gives a plausible but wrong number, soTableTypehas to be honoured.The geo search returns at most 200 results, silently clipping a large radius.
find_cheapest_nearbydetects the cap and says so.
Available Tools
13 toolscalculate_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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
opendata.swiss MCP — Switzerland's federal open-data portal (CKAN catalogue).
Official Swiss data for all 26 cantons and 2,100 communes: tax, rent, health premiums, fuel, jobs.
Free public tax MCP: GST/VAT, income, company & capital-gains tax for 50+ countries, source-cited.
MCP server for Quaderno — tax-rate calculation, invoices, contacts, products, receipts & expenses.
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server providing access to Swiss direct democracy data, covering all federal popular votes since 1848 and elections since 1900.1055 PyPI2MIT
- AlicenseAqualityDmaintenanceAn unofficial MCP server for accessing Swiss Federal Statistical Office (BFS) data.81MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for interacting with Kanton Luzern tax declarations on eSteuern.LU, enabling field catalogue search and live declaration editing.MIT
- AlicenseAqualityBmaintenanceMCP server for the Canton of Bern tax portal TaxMe/BE-Login that reads account statements and tax returns via Playwright browser automation.1311 npmMIT