estv-tax
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-tax Calculate income tax for a single person earning 120k in Zurich for 2026."
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.
Swiss Tax Calculator — MCP Server & Python API
Licensed under MIT by Aiyatullah Saiyed.
A dual-purpose Swiss tax toolkit: use it as a Python API client in your applications, or run it as an MCP server for AI assistants like Claude. Wraps the official ESTV Swiss Federal Tax Calculator — no API key or authentication required.
Covers income, wealth, lump-sum capital, inheritance/gift, and corporate taxes for every Swiss municipality across tax years 2010–2026.
Features
Category | Tools |
Household tax |
|
Compare places |
|
Tax planning |
|
Other taxes |
|
Reference |
|
Related MCP server: Swiss Grounding MCP
Quick Start
Install
# Clone the repository
git clone https://github.com/aiyatullah/swiss-tax-calculator-mcp.git
cd swiss-tax-calculator-mcp
# Install dependencies
uv syncUsage as Python API
Import EstvClient directly in your Python code to query the ESTV tax calculator programmatically.
Basic Example — Find a Location
from estv_mcp import EstvClient
client = EstvClient()
# Search for a municipality by name or postal code
locations = client.search_location("Zug", tax_year=2026)
for loc in locations[:3]:
print(f"{loc['City']} ({loc['Canton']}) — ID: {loc['TaxLocationID']}")Calculate Income Tax
from estv_mcp.api import EstvClient, RELATIONSHIP, CONFESSION, INCOME_TYPE
client = EstvClient()
# Step 1: Find the tax location
locations = client.search_location("8001", tax_year=2026)
location_id = locations[0]["TaxLocationID"]
# Step 2: Get the tax budget (deduction sheet)
budget = client.tax_budget({
"SimKey": None,
"TaxYear": 2026,
"TaxLocationID": location_id,
"Relationship": RELATIONSHIP["single"],
"Confession1": CONFESSION["none"],
"Confession2": 0,
"Children": [],
"Age1": 35,
"RevenueType1": INCOME_TYPE["employed"],
"Revenue1": 120_000,
"Age2": 0,
"RevenueType2": 0,
"Revenue2": 0,
"Fortune": 50_000,
})
# Step 3: Calculate detailed taxes
result = client.detailed_taxes({
"SimKey": None,
"TaxYear": 2026,
"TaxLocationID": location_id,
"Relationship": RELATIONSHIP["single"],
"Confession1": CONFESSION["none"],
"Confession2": 0,
"Children": [],
"Age1": 35,
"RevenueType1": INCOME_TYPE["employed"],
"Revenue1": 120_000,
"Age2": 0,
"RevenueType2": 0,
"Revenue2": 0,
"Fortune": 0,
"Budget": budget,
})
print(f"Total tax: CHF {result['TotalTax']:,.0f}")
print(f"Federal: CHF {result.get('IncomeTaxFed', 0):,.0f}")
print(f"Cantonal: CHF {result.get('IncomeTaxCanton', 0):,.0f}")
print(f"Municipal: CHF {result.get('IncomeTaxCity', 0):,.0f}")Compare Municipalities
from estv_mcp.api import EstvClient, RELATIONSHIP, CONFESSION, INCOME_TYPE, GROUP_CAPITALS
client = EstvClient()
# Compare tax burden across all 26 cantonal capitals
rows = client.many_simple_taxes({
"SimKey": None,
"TaxYear": 2026,
"TaxGroupID": GROUP_CAPITALS,
"Relationship": RELATIONSHIP["single"],
"Confession1": CONFESSION["none"],
"Confession2": 0,
"Children": [],
"Age1": 35,
"RevenueType1": INCOME_TYPE["employed"],
"Revenue1": 100_000,
"Age2": 0,
"RevenueType2": 0,
"Revenue2": 0,
"Fortune": 0,
})
ranked = sorted(rows, key=lambda r: r["TotalTax"])
print("Top 5 cheapest cantonal capitals:")
for r in ranked[:5]:
loc = r["Location"]
print(f" {loc['City']} ({loc['Canton']}): CHF {r['TotalTax']:,.0f}")Inheritance Tax
from estv_mcp.api import EstvClient, BENEFICIARY, GROUP_CAPITALS
client = EstvClient()
# Inheritance tax for a sibling across cantonal capitals
rows = client.many_inheritance_taxes({
"SimKey": None,
"TaxYear": 2026,
"TaxGroupID": GROUP_CAPITALS,
"OnlyGroupID": BENEFICIARY["sibling"][0],
"OnlyPersonID": BENEFICIARY["sibling"][1],
"Donation": False,
"Amount": 500_000,
})
ranked = sorted(rows, key=lambda r: r["TaxTotal"])
print(f"Cheapest: {ranked[0]['Location']['City']} — CHF {ranked[0]['TaxTotal']:,.0f}")
print(f"Most expensive: {ranked[-1]['Location']['City']} — CHF {ranked[-1]['TaxTotal']:,.0f}")Available API Operations
Method | Description |
| Find municipalities by name or postal code |
| Find municipalities within a radius |
| Get the deduction/budget sheet for a household |
| Full tax calculation with breakdown |
| Tax from pre-computed taxable amounts |
| Compare tax across many municipalities |
| Lump-sum capital withdrawal tax across municipalities |
| Inheritance/gift tax across municipalities |
| Corporate tax across municipalities |
| Raw tax bracket tables |
| Supported year range per calculator |
| Current ESTV data version |
Enum Reference
from estv_mcp.api import (
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
GENDER, # male=1, female=2
LANGUAGE, # de=1, fr=2, it=3, en=4
CANTON_GROUP, # AG=1 ... ZH=26
GROUP_CAPITALS, # 88 — all 26 cantonal capitals
GROUP_SWITZERLAND, # 99 — every municipality (~2100)
CALCULATOR, # income_wealth=1, capital_payment=2, legal_entity=3, inheritance=5
BENEFICIARY, # spouse, child, sibling, unrelated, etc. → (GroupID, PersonID)
)Caching
Responses are cached under ~/.cache/estv-mcp for one week. Control via environment variables:
Variable | Effect |
| Disable caching entirely |
| Custom cache directory |
| Cache lifetime in seconds |
Usage as MCP Server
Run this project as an MCP server to give AI assistants (Claude, etc.) access to all Swiss tax tools.
Register with Claude Code
# Project-local (this repo only)
claude mcp add estv-tax -- uv run --directory "$PWD" estv-mcp
# User-wide (available in every project)
claude mcp add -s user estv-tax -- uv run --directory "$PWD" estv-mcpMCP Client Config (JSON)
For any MCP-compatible client, add to your config:
{
"mcpServers": {
"estv-tax": {
"command": "uv",
"args": ["run", "--directory", "/path/to/swiss-tax-calculator-mcp", "estv-mcp"]
}
}
}What the AI Can Do
Once connected, the AI assistant can:
"How much tax would I pay in Zurich on CHF 150,000?" — calls
find_location+calculate_tax"Compare Zug vs Schwyz for a married couple with 2 kids" — calls
compare_locations"Where's the cheapest place within 30km of Zurich HB?" — calls
find_cheapest_nearby"Should I split my pillar 2 withdrawal over multiple years?" — calls
plan_capital_withdrawals"What's the inheritance tax for a sibling in Geneva?" — calls
calculate_inheritance_tax"How much would my company pay in Zug vs Lucerne?" — calls
calculate_company_tax
Development
uv sync # Install dependencies (including dev)
uv run pytest -q # Run tests (hits live ESTV API)
uv run python scripts/stdio_smoke.py # MCP stdio handshake test
uv run ruff check . && uv run ruff format --check . # Lint & format checkGolden Values
tests/golden.json pins known tax figures for closed tax years. The weekly CI run re-checks them against the live API to detect upstream changes.
uv run python scripts/update_golden.py # Update golden values (prints diffs)CI
Tests run on Python 3.11/3.12/3.13 on every push, plus a weekly schedule to catch ESTV data changes.
Important Notes
All amounts are CHF per year
income_type='employed'means gross salary — social contributions (AHV/IV/EO, ALV, NBU, BVG) are derived automaticallyOverride deductions via
deductions={id: value}using IDs fromlist_deductions(e.g.PRAEMIEN3Afor pillar 3a,SCHULDZINSENfor mortgage interest)compare_locations(scope='switzerland')covers ~2,100 municipalities; results are summarized to stay readableChurch tax only applies when
confessionis notnoneFigures are from the official ESTV model — not a binding tax assessment
License
MIT License — see LICENSE.
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 aspect of Swiss tax calculation: location lookup, deduction listing, income tax from gross vs taxable amounts, municipal comparisons, capital payment tax, withdrawal planning, inheritance, company tax, and rate explanation. Even similar tools like compare_locations and find_cheapest_nearby are differentiated by radius constraints and scope. The descriptions clearly separate every tool's role, leaving no ambiguity.
Most tools follow a verb_noun pattern (find_location, list_deductions, calculate_tax, compare_locations), but there are minor deviations: 'deduction_value' is a noun phrase instead of a verb, and 'calculate_tax_from_taxable_amounts' uses a longer prepositional phrase. The pattern is still predictable and readable, with only a couple of outliers.
With 13 tools, the set is well-scoped for a Swiss tax calculator. It covers individual income tax, capital withdrawals, inheritance, company tax, location comparisons, and deduction analysis without unnecessary overlap. Each tool addresses a specific use case an agent would reasonably request, and the count is within the ideal 3-15 range.
The tool surface covers the full tax calculation lifecycle: locating a tax jurisdiction, understanding deductible lines, computing tax from gross income or taxable amounts, comparing municipalities, planning capital withdrawals, and computing special taxes (inheritance, company). Also included are tools for explaining brackets and valuing deductions, making the set comprehensive for the stated domain.
Maintenance
Related MCP Connectors
Demo of a Swiss tax service for AI agents: AI-drafted answers, sample quotes, nothing validated yet.
Official Swiss data for all 26 cantons and 2,100 communes: tax, rent, health premiums, fuel, jobs.
Verifiable US tax oracle for AI agents: cited, machine-checkable federal and state tax computation
Exact French tax & payroll calculations for AI agents: income tax (impôt sur le revenu: parts, quotient familial, décote, TMI), micro-entrepreneur URSSAF contributions (ACRE, versement libératoire) with an optional VAT franchise check (franchise en base de TVA: must I charge VAT?), and gross-to-net salary with employer cost — CDI or CDD (prime de précarité, congés payés), full-time or part-time. Missing information? Your agent gets, for free, the exact questions to ask the user (in French, with types and allowed values) in a single round trip. Deterministic, no LLM: matches all 7,095 values of the official DGFiP tax tables, 60 cases from the official simulators and the official worked examples of the tax doctrine (BOFiP). Unsupported cases are refused for free; you pay $0.005 in USDC via x402 only when the calculation succeeds. Free catalogue tool: list_france_calculators.
Related MCP Servers
- FlicenseAqualityDmaintenanceMCP server for the Swiss federal tax calculator, providing income, wealth, inheritance, and corporate tax figures for all Swiss municipalities and tax years 2010-2026.132-
- FlicenseAqualityCmaintenanceEnables AI assistants to provide authoritative, cited, jurisdiction-correct answers about Switzerland using official federal, cantonal, and municipal sources across multiple languages and topics.13-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to plan and price household employment in Switzerland (cleaner, nanny, carer), returning hiring checklists with real deadlines, employer costs and net wages, minimum-wage checks, and rules for all 26 cantons through read-only tools. Every figure is tied to its official source document and verification date.1CC BY-4.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to work out the tourist, city, occupancy and hotel taxes a stay adds on top of the room price, night by night, for given dates, guests and room cost, with each figure tied to its official source and check date. It also exposes full local rules (rates, seasons, caps, exemptions) for researched places and returns links to live hotel and rental prices.Apache 2.0