Cadastro Predial PT
README.md
<!-- mcp-name: io.github.MaximusSoroka/cadastro-pt-mcp -->
# cadastro-pt-mcp
Read-only [MCP](https://modelcontextprotocol.io/) server for the official **Cadastro Predial** (property cadastre) of the Direção-Geral do Território (DGT), Portugal.
## Licence (two layers)
- **This software** is licensed under the [MIT License](LICENSE). Copyright (c) 2026 Maximus Soroka.
- **The cadastre data** returned by the tools are **not** MIT-licensed. They remain under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) of the Direção-Geral do Território. Every tool response includes the required credit:
**Carta Cadastral Digital – Sistema Nacional de Informação Cadastral – Direção-Geral do Território (CC BY 4.0)**
Official API: <https://ogcapi.dgterritorio.gov.pt/collections/cadastro>
Metadata: <https://snig.dgterritorio.gov.pt/rndg/srv/por/catalog.search#/metadata/73282c48-7f23-435c-ba41-592a96470080>
- **Municipality names and DICO/DTMN codes** bundled for name search come from the official **Carta Administrativa Oficial de Portugal (CAOP2025), Municípios, Continente**, also CC BY 4.0. Required credit: «Informação geográfica cedida pela Direção-Geral do Território». Collection: <https://ogcapi.dgterritorio.gov.pt/collections/municipios>. See `src/cadastro_pt_mcp/data/README.md`.
## Disclaimer
Results are **not official**. This is **not** a *certidão permanente* and **not** a *caderneta predial*. The Cadastro Predial covers only **118 municipalities** in mainland Portugal (DGT, 3 February 2023, page updated 25 March 2025: 111 CGPR + 7 Cadastro Predial), not the whole country. **Porto** is a valid CAOP2025 municipality with **no cadastre parcels**. **Lisboa** has only a handful of isolated parcels (not city-wide; the centre is typically empty). No warranty.
---
## English
### Install
Python 3.11 or newer. From a local checkout:
```bash
python3 -m venv .venv
.venv/bin/pip install -e .
```
Or, once the package is published on PyPI (it is not published yet):
```bash
pip install cadastro-pt-mcp
```
The official MCP Python SDK v2 is used. In that version **FastMCP was renamed to `MCPServer`**.
### Run
```bash
cadastro-pt-mcp
# or
python -m cadastro_pt_mcp
```
### Claude Desktop / Cursor (generic paths)
Add a local MCP server. Use your own checkout path; do not copy machine-specific directories.
After `pip install -e .` in the checkout, the console script is enough:
```json
{
"mcpServers": {
"cadastro-pt-mcp": {
"command": "cadastro-pt-mcp"
}
}
}
```
If you prefer to call the venv interpreter explicitly:
```json
{
"mcpServers": {
"cadastro-pt-mcp": {
"command": "/path/to/cadastro-pt-mcp/.venv/bin/python",
"args": ["-m", "cadastro_pt_mcp"]
}
}
}
```
On Claude Desktop this usually goes in `claude_desktop_config.json`. In Cursor, add it under MCP server settings. No API key is required.
### Tools
1. `parcel_at_point(lat, lon)` — parcel containing a WGS84 point, if any.
2. `parcels_in_area(concelho | bbox, limit)` — up to 20 rows. `concelho` may be an official name (accent- and case-insensitive, e.g. `lourinha` or `Lourinhã`), a 4-digit DICO code (`1108`), or a 6-digit parish code. `bbox` is `min_lon,min_lat,max_lon,max_lat` (max. about 5 km). Do not pass both.
3. `coverage_check(lat/lon | concelho)` — is the place in the cadastre? An empty point may still sit in a covered municipality (road, water, gap); the tool then checks about 800 m around it. Named municipalities get a clear coverage message: Porto has none; Lisboa has only isolated parcels, not city-wide coverage.
### Examples
```bash
python - <<'PY'
from cadastro_pt_mcp import client as c
# Covered municipality, name without accent
print(c.to_json(c.coverage_check(concelho="lourinha")))
# Official name, upper case — not in the cadastre
print(c.to_json(c.coverage_check(concelho="LISBOA")))
# Porto is also a valid CAOP municipality with no cadastre parcels
print(c.to_json(c.coverage_check(concelho="Porto")))
PY
```
Live checks (few polite requests):
```bash
python tests/test_live.py
```
### Limits
- Only 118 municipalities, not the whole country. Porto currently has no parcels. Lisboa has only isolated records, not city-wide coverage.
- The bundled name list is mainland CAOP2025 only (278 municipalities). Azores and Madeira are not in that extract.
- Name search is exact, then unique prefix, then unique substring. Ambiguous queries (for example `Oliveira`) must use a 4-digit code.
- The client caps page size (20), bounding-box size and timeouts. Do not bulk-download the dataset.
---
## Deutsch
Schlanker, nur lesender MCP-Server für den offiziellen **Cadastro Predial** der DGT.
### Lizenzen
Die **Software** steht unter der MIT-Lizenz (Copyright 2026 Maximus Soroka). Die **Daten** der Tools stehen unter **CC BY 4.0 der DGT** und brauchen die Namensnennung:
**Carta Cadastral Digital – Sistema Nacional de Informação Cadastral – Direção-Geral do Território (CC BY 4.0)**
Concelho-Namen und DICO-Codes stammen aus der **CAOP2025 (Municípios, Continente)**, ebenfalls CC BY 4.0. Pflichttext: «Informação geográfica cedida pela Direção-Geral do Território».
### Hinweis
Ergebnisse sind **nicht amtlich**. Dies ist **keine Certidão permanente** und **keine Caderneta predial**. Der Cadastro deckt nur **118 Concelhos** in Portugal continental ab, nicht das ganze Land. **Porto** ist ein gültiger CAOP2025-Concelho ohne Cadastro-Flurstücke. **Lisboa** hat nur wenige isolierte Flurstücke, nicht flächendeckend (das Zentrum typischerweise leer). Keine Gewähr.
### Setup
Python 3.11+. Im lokalen Checkout:
```bash
python3 -m venv .venv
.venv/bin/pip install -e .
cadastro-pt-mcp
```
### Claude Desktop / Cursor
Generische Pfade verwenden, keine rechnerspezifischen Verzeichnisse übernehmen. Nach der Installation reicht der Entry-Point `cadastro-pt-mcp`. Alternativ:
```json
{
"mcpServers": {
"cadastro-pt-mcp": {
"command": "/path/to/cadastro-pt-mcp/.venv/bin/python",
"args": ["-m", "cadastro_pt_mcp"]
}
}
}
```
Kein API-Schlüssel. Namen der Concelhos sind unabhängig von Akzenten und Groß-/Kleinschreibung (Beispiel: `lourinha` findet Lourinhã, Code 1108).
### Grenzen
Nur 118 Concelhos. Porto derzeit ohne Flurstücke; Lisboa nur isolierte Nachweise, nicht die ganze Stadt. Die Namensliste umfasst nur das Festland (CAOP2025, 278 Concelhos). Höfliche Nutzung: Limit 20, kleine Bounding-Boxen, Timeouts. Kein Massenabzug.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues