# permisapi-mcp

<!-- mcp-name: fr.permisapi/permisapi -->

Serveur **MCP** (Model Context Protocol) pour [PermisAPI](https://permisapi.fr).

Il permet à **Claude**, **ChatGPT**, **Claude Desktop**, **Cursor**, **Windsurf** ou tout
client compatible MCP d'interroger en langage naturel **1,3 million de permis de construire
en France** (base Sitadel, permis autorisés depuis 2013, 101 départements, logements et
locaux).

18 outils en lecture seule : recherche par critères ou par adresse, **score d'opportunité
marchand de biens v0.3 et son explication** (les 11 signaux pondérés, commentés en
français), ventes immobilières voisines (DVF, ventes de 2021 à 2025) et prix au m²,
zonage PLU, risques Géorisques (inondation, séisme, sites Seveso proches…), parcelle
cadastrale DGFiP, **bâtiments existants** (terrain nu ou déjà bâti), **parcelles voisines**,
**recherche dans un polygone GeoJSON** (ZAC, périmètre d'opération), statistiques de
densité par commune, **budget de chantier estimé** et **entreprises du bâtiment proches**
(base SIRENE, codes NAF 41, 42 et 43), enrichissement d'une liste.

## Deux façons de l'utiliser

### 1. Serveur hébergé (recommandé, rien à installer)

Adresse : `https://mcp.permisapi.fr/mcp`

- **Claude et ChatGPT** : ajoutez un connecteur personnalisé à cette adresse. Une page
  PermisAPI s'ouvre ; collez-y votre clé (ou créez-y un compte Gratuit) et cliquez sur
  **Autoriser** (OAuth avec PKCE : l'assistant reçoit un jeton, jamais votre clé). Les intitulés des menus changent
  d'une version à l'autre : le pas à pas à jour est sur
  [permisapi.fr/mcp](https://permisapi.fr/mcp).
- **Cursor, Windsurf et autres clients** acceptant un en-tête (`~/.cursor/mcp.json`) :

```json
{
  "mcpServers": {
    "permisapi-hosted": {
      "url": "https://mcp.permisapi.fr/mcp",
      "headers": { "Authorization": "Bearer pk_live_VOTRE_CLE" }
    }
  }
}
```

Transports : Streamable HTTP (spécification MCP actuelle) sur `/mcp` et `/mcp/`, et SSE
historique sur `/sse` + `/messages/`. Le serveur ne conserve ni vos questions ni les
résultats : il relaie vos appels vers `api.permisapi.fr`. Quand la mesure d'audience est
activée sur le serveur (PostHog, hébergement UE), chaque appel d'outil y est compté (nom
de l'outil, durée, statut, formule).

### 2. En local (Claude Desktop, mode stdio)

Pour Claude Desktop, ou si vous préférez tout faire tourner sur votre machine, installez
le paquet `permisapi-mcp`.

## Prérequis

- **Python 3.10 ou plus récent** (exigé par le SDK MCP)
- Une clé PermisAPI : [permisapi.fr/#pricing](https://permisapi.fr/#pricing) (formule
  Gratuit, sans carte bancaire)

## Installation

Vérifiez d'abord la version de Python :

```bash
python --version       # macOS / Linux / Windows
```

Si elle est `>= 3.10` :

```bash
pip install permisapi-mcp
```

Sinon, voir [Dépannage](#dépannage) plus bas (solution `uvx` en une commande, sans
changer le Python du système).

## Configuration de Claude Desktop

Modifiez `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou
`%APPDATA%\Claude\claude_desktop_config.json` (Windows) :

```json
{
  "mcpServers": {
    "permisapi": {
      "command": "permisapi-mcp",
      "env": {
        "PERMISAPI_KEY": "pk_live_VOTRE_CLE"
      }
    }
  }
}
```

Redémarrez Claude Desktop. Vous pouvez alors demander :

> *« Liste les permis de logement autorisés à Paris ce mois-ci »*
>
> *« Trouve des permis autour de la rue de Passy à Paris »*
>
> *« Quel est le zonage PLU du permis 07510125V0025 ? »* (formule Régional et plus)

**Périmètre géographique selon la formule** (`src/services/plan_gating.py`) :

- **Gratuit** : 1 département, les nouveaux permis des 2 dernières publications Sitadel
  (environ 2 mois), 500 requêtes par mois.
- **Découverte** : 1 département, 6 mois d'historique, 2 000 requêtes par mois.
- **Explorateur** : 5 départements, 12 mois d'historique, 5 000 requêtes par mois.
- **Régional** : 5 départements, historique complet et données avancées (ventes DVF,
  score, PLU, risques, cadastre, budget, entreprises).
- **Pro** : les mêmes données avancées sur la France entière.
- **Business** et **Entreprise** : France entière, plus la recherche par polygone, la
  densité par commune et l'enrichissement de liste.

Pour les formules à départements (Gratuit, Découverte, Explorateur, Régional), chaque nouveau
département interrogé s'ajoute à votre périmètre jusqu'à la limite de la formule ; le
choix est ensuite définitif pour cette formule. Les exemples ci-dessus portent sur Paris
(75).

## Configuration de Cursor, Windsurf et autres clients

Guide complet : [permisapi.fr/mcp](https://permisapi.fr/mcp)

## Outils disponibles (18)

| Outil | Route | Formules |
|---|---|:---:|
| `search_permits` | GET /v1/permits (12 filtres et un tri) | Toutes |
| `get_permit_details` | GET /v1/permits/{num_pa} | Toutes |
| `fuzzy_search_addresses` | GET /v1/search?q=texte (recherche approchée) | Toutes |
| `find_dvf_neighbors` | GET /v1/permits/{num_pa}/dvf (ventes DVF 2021-2025, prix médian au m²) | Régional et plus |
| `get_mdb_score` | GET /v1/permits/{num_pa}/score (score v0.3, 11 signaux) | Régional et plus |
| `get_score_explanation` | GET /v1/permits/{num_pa}/score/explain (11 signaux commentés, principaux leviers) | Régional et plus |
| `get_plu_zoning` | GET /v1/permits/{num_pa}/plu | Régional et plus |
| `get_risks` | GET /v1/permits/{num_pa}/risks (Géorisques) | Régional et plus |
| `get_parcelle_geometry` | GET /v1/permits/{num_pa}/parcelle (cadastre DGFiP) | Régional et plus |
| `get_existing_buildings` | GET /v1/permits/{num_pa}/batiments-existants (terrain nu ou bâti) | Régional et plus |
| `get_parcelle_by_id` | GET /v1/parcelles/{id_parcelle} (identifiant cadastral de 14 caractères) | Régional et plus |
| `get_neighbor_parcels` | GET /v1/permits/{num_pa}/parcelles-voisines (rayon de 10 à 2 000 m) | Régional et plus |
| `get_permit_full_view` | GET /v1/permits/{num_pa}/360 (vue complète en un appel) | Régional et plus (détail seul en Gratuit, Découverte et Explorateur) |
| `get_economics` | GET /v1/permits/{num_pa}/economics (budget de chantier : fourchette, scénario, lots) | Régional et plus |
| `get_contractors` | GET /v1/permits/{num_pa}/contractors (entreprises du bâtiment proches, par métier) | Régional et plus |
| `search_permits_in_polygon` | POST /v1/permits/inside-polygon (polygone GeoJSON) | Business et Entreprise |
| `get_commune_density_stats` | GET /v1/stats/commune/{code}/density (parcelles, bâtiments, permis) | Business et Entreprise |
| `bulk_enrich_list` | POST /v1/permits/bulk-enrich (liste de 1 000 lignes au plus) | Business et Entreprise |

« Régional et plus » = Régional, Pro, Business et Entreprise. Les autres formules
reçoivent une erreur 402.

## Sécurité

- En mode local, la clé reste sur votre machine (variable d'environnement) ; en mode
  hébergé, l'assistant ne reçoit qu'un jeton. Dans les deux cas, le modèle ne voit jamais
  la clé, seulement les arguments des outils.
- Validation stricte des entrées (`num_pa`, identifiants cadastraux, codes INSEE, bornes
  numériques).
- 16 outils en consultation (GET) et 2 en POST (`bulk_enrich_list`, qui croise une liste
  que vous fournissez, et `search_permits_in_polygon`, qui reçoit un polygone). Tous sont
  en lecture seule : ils ne modifient ni votre compte ni les données.

## Dépannage

### `pip install permisapi-mcp` répond « package introuvable » ou « no matching distribution »

Cause la plus fréquente : votre Python est antérieur à 3.10, minimum exigé par le SDK MCP.

Vérifiez :

```bash
python --version       # ou python3 --version
```

Si elle est `< 3.10`, deux solutions au choix.

**Solution A (recommandée, 30 secondes) : `uvx` avec une version de Python imposée**

`uvx` installe et lance le serveur dans un Python isolé, à la version voulue, sans toucher
à votre installation.

```bash
# 1. Installer uv (une seule fois)
curl -LsSf https://astral.sh/uv/install.sh | sh         # macOS / Linux
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows PowerShell

# 2. Lancer le serveur
uvx --python 3.11 permisapi-mcp
```

Puis, dans la configuration de Claude Desktop, remplacez `"command": "permisapi-mcp"`
par :

```json
{
  "mcpServers": {
    "permisapi": {
      "command": "uvx",
      "args": ["--python", "3.11", "permisapi-mcp"],
      "env": { "PERMISAPI_KEY": "pk_live_VOTRE_CLE" }
    }
  }
}
```

**Solution B : mettre à jour le Python du système**

- macOS : `brew install python@3.11`
- Windows : télécharger https://www.python.org/downloads/ et cocher « Add to PATH »
- Linux : `sudo apt install python3.11` (ou l'équivalent de votre distribution)

Puis `pip3.11 install permisapi-mcp`.

Guide complet et autres questions : [permisapi.fr/mcp](https://permisapi.fr/mcp)

## Licence

MIT pour le code. Données publiques : SDES (Sitadel), DGFiP (DVF, cadastre), Géorisques,
IGN (Géoportail de l'Urbanisme), INSEE (SIRENE).

## Support

evan@permisapi.fr

## Code source

[github.com/Evan-Crx/permisapi-mcp](https://github.com/Evan-Crx/permisapi-mcp)