# permisapi-mcp 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)