immo-mcp

immo-mcp

An MCP (Model Context Protocol) server for French real-estate market analysis, built exclusively on open data sources. No third-party site automation.

Data sources

| Source | What it provides | |--------|-----------------| | DVF Etalab | All notarised property transactions in France (2018-present) | | OpenDataSoft DVF API | Same DVF data, queryable without a local DB | | ADEME DPE-v2 | Energy-performance certificates (DPE) | | Géorisques | Flood, seismic, radon, ICPE risk data | | CRE | Regulated electricity tariffs | | INSEE | Postal code → INSEE commune lookup | | Nominatim / Overpass OSM | Geocoding and points of interest |

MCP tools

| Tool | Description | |------|-------------| | dvf | Search DVF transactions by city / postal code / department | | dvf_stats | Aggregate price statistics from DVF (median, p25/p75, …) | | dvf_db_info | Report on the local DuckDB DVF database | | pappers_immo | DVF statistics via the OpenDataSoft public API | | detect_underpriced | Compare a market segment against DVF + ODS reference prices | | dpe | Search DPE certificates by city or postal code | | georisques | Risk analysis for a location (flood, seismic, radon, ICPE) | | list_georisques_kinds | List available Géorisques risk categories | | electricity_tariff | Fetch current regulated electricity tariffs (CRE) | | insee_lookup | Resolve a postal code to its INSEE commune codes | | geocode | Forward geocode an address via Nominatim | | pois | Search points of interest around a location (OSM Overpass) | | list_poi_categories | List available POI category presets | | listings_stats | Compute price statistics on a list of listings | | listings_gap | Annotate listings with gap-from-median percentage |

Quick start

1. Install

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. (Optional) Build a local DVF database

For faster, offline DVF queries you can build a local DuckDB:

# Requires Docker
cd docker/dvf
DVF_HOST_DATA_DIR=~/.immo-mcp/dvf docker compose up

The MCP server will look for the database at ~/.immo-mcp/dvf/dvf.duckdb. Without it, the dvf tool falls back to the OpenDataSoft API automatically.

3. Start the server

python -m immo_mcp.server

4. Connect from Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "immo-mcp": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "immo_mcp.server"]
    }
  }
}

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | DVF_DB_PATH | ~/.immo-mcp/dvf/dvf.duckdb | Path to local DuckDB DVF file | | IMMO_CACHE_DB | ~/.immo-mcp/listings.db | SQLite listing cache |

Development

pip install -r requirements.txt
pytest

License

MIT — see LICENSE.