Skip to main content
Glama
estv-tax

estv-tax

by Aiyatullah

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

find_location, calculate_tax, list_deductions, calculate_tax_from_taxable_amounts

Compare places

compare_locations, find_cheapest_nearby

Tax planning

plan_capital_withdrawals, deduction_value

Other taxes

calculate_capital_payment_tax, calculate_inheritance_tax, calculate_company_tax

Reference

explain_tax_brackets, get_tax_years


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 sync

Usage 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

search_location(query, tax_year)

Find municipalities by name or postal code

search_location_geo(lat, lon, radius_km, tax_year)

Find municipalities within a radius

tax_budget(payload)

Get the deduction/budget sheet for a household

detailed_taxes(payload)

Full tax calculation with breakdown

simple_taxes(payload)

Tax from pre-computed taxable amounts

many_simple_taxes(payload)

Compare tax across many municipalities

many_capital_taxes(payload)

Lump-sum capital withdrawal tax across municipalities

many_inheritance_taxes(payload)

Inheritance/gift tax across municipalities

many_legal_entity_taxes(payload)

Corporate tax across municipalities

export_tax_scales(tax_year, tax_group_id)

Raw tax bracket tables

tax_year_range(calculator)

Supported year range per calculator

tax_version()

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

ESTV_MCP_NO_CACHE=1

Disable caching entirely

ESTV_MCP_CACHE_DIR=/path

Custom cache directory

ESTV_MCP_CACHE_TTL=3600

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-mcp

MCP 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 check

Golden 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 automatically

  • Override deductions via deductions={id: value} using IDs from list_deductions (e.g. PRAEMIEN3A for pillar 3a, SCHULDZINSEN for mortgage interest)

  • compare_locations(scope='switzerland') covers ~2,100 municipalities; results are summarized to stay readable

  • Church tax only applies when confession is not none

  • Figures are from the official ESTV model — not a binding tax assessment


License

MIT License — see LICENSE.

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.1/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      MCP server for the Swiss federal tax calculator, providing income, wealth, inheritance, and corporate tax figures for all Swiss municipalities and tax years 2010-2026.
      13
      2
      -
    • F
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to provide authoritative, cited, jurisdiction-correct answers about Switzerland using official federal, cantonal, and municipal sources across multiple languages and topics.
      13
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      CC BY-4.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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