mcp

# flatin.pt MCP server — Portuguese property taxes

An [MCP](https://modelcontextprotocol.io) server that answers the questions people ask before buying a home in Portugal: **how much IMT and stamp duty on top of the price**, and **what yearly IMI rate a municipality sets** — for all 308 municipalities, with the source and the year of every number.

It is run by [flatin.pt](https://flatin.pt/en/) and listed in the official MCP Registry as [`pt.flatin/property-taxes`](https://registry.modelcontextprotocol.io/v0.1/servers/pt.flatin%2Fproperty-taxes/versions/latest).

```
You:    I'm buying a flat in Matosinhos for 280 000 €. What do I pay on top, and what's the IMI there?

Claude: [imt_calculate value="280000"]  [imi_rate municipality="Matosinhos"]
        IMT 9 142,04 €, stamp duty 2 240,00 €, deed and registration about 900 € —
        12 282,04 € on top of the price.
        IMI in Matosinhos (Porto): 0,37 % a year on the taxable value (VPT), 2025 table.
        Source: Autoridade Tributária tables, computed by flatin.pt.
```

## Tools

| Tool | What it answers |
|---|---|
| `imt_calculate` | What a purchase costs on top of the price: IMT (transfer tax), Imposto do Selo (stamp duty) and an estimate for the deed and registration. Official 2026 tables, including the reduced IMT table and the stamp duty deduction for buyers aged 35 or under. |
| `imi_rate` | The yearly property tax (IMI) rate of one municipality, by name or four-digit code, with its history since 2023. Where a municipality sets no single rate (it is set per parish), the answer says so instead of returning zero. |
| `imi_annual_cost` | Yearly IMI for an urban property with a given taxable value (VPT). VPT is the tax authority's valuation, not the purchase price. |
| `request_consultation` | How to reach a licensed real estate agency (AMI): the form link and the GDPR consent text in the user's language. The request is sent by the person, never on their behalf. |

Every successful answer carries an `attribution` field — who computed it, from which table and year, and a link to the primary source. Please show it to the user: numbers without a source cannot be checked.

## Connect

The server is **remote** — nothing to install. Point your client at:

```
https://flatin.pt/mcp
```

**Claude Code**

```bash
claude mcp add --transport http flatin https://flatin.pt/mcp
```

**Clients that can only start a local process** (stdio) — use the bridge in this repository. It needs Node.js 18.17 or newer and has no dependencies:

```bash
claude mcp add flatin -- npx -y github:devflatinpt/mcp
```

```json
{
  "mcpServers": {
    "flatin": {
      "command": "npx",
      "args": ["-y", "github:devflatinpt/mcp"]
    }
  }
}
```

The bridge forwards each JSON-RPC message to `https://flatin.pt/mcp` and writes the answer back. It stores nothing and sends nothing except what your client sends. Set `FLATIN_MCP_URL` to point it elsewhere.

**Docker**

```bash
docker build -t flatin-mcp . && docker run -i --rm flatin-mcp
```

## The data behind it

- **IMI rates, all 308 municipalities**, checked line by line against the Autoridade Tributária portal — [open data page](https://flatin.pt/en/tools/imi-open-data/), [CSV](https://flatin.pt/api/v1/imi/rates.csv), licence CC BY 4.0.
- **IMT and stamp duty** from the official 2026 tables — the same numbers as the [IMT calculator](https://flatin.pt/en/tools/imt-calculator/).
- **REST API** with the same functions: [API and data](https://flatin.pt/en/tools/api-and-data/) · [OpenAPI schema](https://flatin.pt/api/openapi.json).

The MCP server, the API and the website call the same code, so the three never disagree by a cent.

## Guides

- [Buying property in Portugal: costs and taxes](https://flatin.pt/en/guides/buying-property-portugal-costs-taxes/)
- [NIF and residency for foreign buyers](https://flatin.pt/en/guides/nif-residency-foreign-buyers/)
- In Portuguese: [Comprar casa: custos e impostos](https://flatin.pt/pt/guias/comprar-casa-custos-impostos/) · [Calculadora de IMT](https://flatin.pt/pt/ferramentas/calculadora-imt/)

## Development

```bash
node --test
```

This repository is published from the flatin.pt codebase; issues and suggestions are welcome here.

## Licence

MIT — see [LICENSE](LICENSE). The data returned by the server is licensed separately under CC BY 4.0.