Skip to main content
Glama
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.