Skip to main content
Glama
datafordeler-mcp

datafordeler-mcp

by JulianUmbhau
README.md
# datafordeler-mcp

An [MCP](https://modelcontextprotocol.io) server for Danish buildings and addresses. It lets a model:

- find an address from free text,
- look up the address's details and coordinates,
- read the BBR buildings and units registered there: use, year built, areas, materials, heating installation and
  medium, housing type, rooms, and more. Code values come with their official Danish text.

It calls the official services live on each request:

| Data | Service | Credential |
|---|---|---|
| Addresses (DAR) | [Adressevælger](https://confluence.kds.dk/pages/viewpage.action?pageId=234782998), Klimadatastyrelsen's replacement for DAWA autocomplete | none |
| Buildings and units (BBR) | [Datafordeler GraphQL](https://confluence.kds.dk/display/DML/GraphQL), `BBR/v3` | `DATAFORDELER_API_KEY` |

It uses no DAWA (closed in 2026) and no legacy Datafordeler REST or username/password login (both end 15 January 2027).

## Tools

| Tool | Input | Returns |
|---|---|---|
| `address_search` | `text`, `level` (`adresse` or `husnummer`), `limit` | DAR ids and labels of the matching addresses |
| `address_get` | `id` of a unit address or a husnummer | full address, postcode, municipality and road code, husnummer id, coordinates |
| `bbr_buildings` | one of `husnummer_id`, `address_id`, `building_id`, `jordstykke_id`; `limit` | BBR buildings (`byg0xx` fields) |
| `bbr_units` | one of `address_id`, `building_id`, `unit_id`; `limit` | BBR units (`enh0xx` fields) |

- Coded fields come as `{"code": "1", "text": "Fjernvarme/blokvarme"}`, and empty fields are left out.
- Coordinates are EPSG:25832 (ETRS89 / UTM 32N, metres).
- Every BBR query asks for the data as registered and valid now.
- `results` and `count` hold only buildings and units that stand now (status `6 Opført`). BBR keeps demolished buildings
  (status `10 Historisk`), and also holds planned, under-construction and shelved ones. These are listed apart in
  `not_existing`, each with a `state`. Objects registered by mistake (`11 Fejlregistreret`) are only counted.

### Building states

BBR's own values are never changed. Every row keeps its `status` code and official text. `state` and the grouping
are this server's reading:

| Status | `state` | Basis |
|---|---|---|
| 6 Opført | in `results` | BBR [D0130 Logisk Intern Datamodel](https://teknik.bbr.dk/file/666026/d0130-logisk-intern-datamodel-bbr-1_8.docx), section 3.2 |
| 2 Projekteret | planned | D0130 |
| 3 Under opførsel | under construction | D0130 |
| 10 Historisk | demolished or otherwise ceased | D0130: "ved nedrivning af en bygning sættes status til historisk" |
| 14 Henlagt | shelved, never built | D0130 |
| 11 Fejlregistreret | only counted | D0130: registered by mistake |
| 9 Afsluttet | closed without being built | inferred: in a November 2026 sample, no status-9 building had a year built |
| 13 Delvis afsluttet | partly completed, may be partly in use | inferred: most have a year built and heating. D0130 does not list this status for buildings, but BBR uses it. |
| 12 Midlertidig afsluttet | status unclear | not defined in D0130, and mixed in the data |

## Setup

1. Create an IT-system with an API key in [Datafordeler Administration](https://portal.datafordeler.dk). A new key
   takes about 15 minutes to become active.
2. Install [uv](https://docs.astral.sh/uv/).
3. Add the server to your MCP client, for example Claude Code:

```sh
claude mcp add datafordeler -e DATAFORDELER_API_KEY=<key> -- \
  uvx --from git+https://github.com/JulianUmbhau/datafordeler-mcp datafordeler-mcp
```

Or in a JSON client config:

```json
{
  "mcpServers": {
    "datafordeler": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/JulianUmbhau/datafordeler-mcp", "datafordeler-mcp"],
      "env": { "DATAFORDELER_API_KEY": "<key>" }
    }
  }
}
```

| Environment variable | |
|---|---|
| `DATAFORDELER_API_KEY` | required for the BBR tools |
| `ADRESSEVAELGER_TOKEN` | optional. Adressevælger has no user accounts yet and asks everyone to send `adressevaelger123`, the default. Set your own token once accounts arrive. |

`datafordeler-mcp --self-test` checks the installation offline: the tools are registered and the code lists translate.

## Development

```sh
uv sync
uv run ruff check
uv run pytest                      # offline, HTTP mocked
cp .example.env .env               # then fill in DATAFORDELER_API_KEY
set -a; . ./.env; set +a; uv run pytest -m live
uv run scripts/update_codes.py     # refresh src/datafordeler_mcp/codes.json from teknik.bbr.dk
```

## Data and licences

The code is MIT-licensed. The data keeps its own terms:

- **BBR:** Bygnings- og Boligregistret (BBR), [CC BY 4.0](https://datafordeler.dk/vejledning/brugervilkaar/bygnings-og-boligregistret-bbr/).
  The code lists come from [teknik.bbr.dk/kodelister](https://teknik.bbr.dk/kodelister).
- **DAR:** Danmarks Adresseregister, Klimadatastyrelsen, [CC BY 4.0](https://datafordeler.dk/vejledning/brugervilkaar/danmarks-adresseregister-dar/).

Credit these sources when you share results. Every tool result carries a `source` line for this.

## Related

[boligmcp](https://github.com/flyngaa/boligmcp) (MIT) is a much broader property-report MCP server over the same
services: ownership, valuation, sales, plans and more. This project covers only addresses, buildings and units.