# 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](https://files.data.gouv.fr/geo-dvf/) | All notarised property transactions in France (2018-present) |
| [OpenDataSoft DVF API](https://public.opendatasoft.com/) | Same DVF data, queryable without a local DB |
| [ADEME DPE-v2](https://data.ademe.fr/) | Energy-performance certificates (DPE) |
| [Géorisques](https://www.georisques.gouv.fr/) | Flood, seismic, radon, ICPE risk data |
| [CRE](https://www.cre.fr/) | Regulated electricity tariffs |
| [INSEE](https://api.insee.fr/) | Postal code → INSEE commune lookup |
| [Nominatim / Overpass OSM](https://nominatim.openstreetmap.org/) | 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

```bash
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:

```bash
# 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

```bash
python -m immo_mcp.server
```

### 4. Connect from Claude Desktop

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

```json
{
  "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

```bash
pip install -r requirements.txt
pytest
```

## License

MIT — see [LICENSE](LICENSE).