Evan-Crx/permisapi-mcp

Serveur MCP (Model Context Protocol, Anthropic) pour PermisAPI.

Permet à Claude Desktop, Claude.ai web, ChatGPT custom GPT, Cursor, Windsurf ou tout client MCP-compatible de consulter 1,2 M+ permis de construire de France (Sitadel 2014-2026, résidentiel + non-résidentiel, depuis 2014) en langage naturel.

18 outils disponibles : recherche par adresse, score d'opportunité Marchand de Biens v0.3 et son explication transparente (les 11 signaux pondérés détaillés en français avec interprétation contextualisée), prix au m² des ventes voisines sur 12 ans, zonage urbanisme PLU, risques (inondation, sismique, ICPE), parcelle cadastre DGFiP (par identifiant Etalab ou par géométrie), bâtiments existants (terrain nu vs déjà bâti), parcelles voisines d'un permis (pattern d'activité local marchand de biens), recherche par polygone GeoJSON custom (ZAC, périmètre opération), statistiques densité commune, budget chantier estimé (fourchette EUR

• scénario neuf / rénovation / démolition basé surfaces Sitadel + barème Capeb / FFB + INSEE ICP-BT), entreprises BTP locales par lot (SIRENE NAF 41/42/43, 1 086 952 actifs en BDD géolocalisés WGS84) et enrichissement de liste client.

Deux modes au choix

Mode 1 : SSE hosted (recommandé, zéro installation)

Connecte directement Claude.ai web ou ChatGPT à https://mcp.permisapi.fr/mcp avec ta clé PermisAPI en Bearer token. Pas de Python à installer, pas de config locale, ça marche depuis n'importe quel browser.

Claude.ai web (Settings > Integrations > Add MCP server) :

URL    : https://mcp.permisapi.fr/mcp
Auth   : Bearer
Token  : pk_live_VOTRE_CLE

Cursor / Windsurf (~/.cursor/mcp.json) :

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

Mode supporté : Streamable HTTP (spec actuelle MCP) sur /mcp ET SSE legacy sur /sse + /messages/ (backward compat). Aucune donnée n'est stockée côté serveur MCP, c'est un proxy authentifié vers api.permisapi.fr.

Mode 2 : stdio local (Claude Desktop classique)

Pour Claude Desktop ou si tu préfères tout en local, install Python et le package permisapi-mcp :

Pré-requis

• Python 3.10 ou plus récent (requis par le MCP SDK Anthropic, non négociable)
• Une clé PermisAPI : https://permisapi.fr/#pricing (gratuite pour commencer)

Installation

Vérifier d'abord la version Python :

python --version       # macOS / Linux / Windows

Si >= 3.10 :

pip install permisapi-mcp

Si < 3.10, voir la section Troubleshooting plus bas (workaround uvx en 1 commande, pas besoin d'upgrade système).

Configuration Claude Desktop

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

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

Redémarrez Claude Desktop. Vous pouvez maintenant demander :

« Liste les permis de logement déposés à Paris ce mois avec un score MDB > 70 »

« Trouve-moi des opportunités MDB autour de la rue de Passy à Paris »

« Quel est le zonage PLU du permis 0930662500027 ? »

Note sur le périmètre géographique :

• Free : 1 département au choix (Paris par défaut). Modifiable via le dashboard.
• Explorer : 5 départements au choix (Paris/Lyon/Marseille/Bordeaux/Toulouse par défaut).
• Pro / Business / Enterprise : France entière, aucune restriction géographique.

Les exemples ci-dessus ciblent Paris (75) pour qu'ils fonctionnent immédiatement sur tous les plans. Si vous êtes sur Explorer avec ses départements par défaut, vous pouvez aussi demander "à Lyon", "à Bordeaux", etc.

Configuration Cursor / Windsurf / autres clients

Voir le guide complet : https://permisapi.fr/mcp

Tools disponibles (18)

Tool	Endpoint	Plan
search_permits	GET /v1/permits (13 filtres)	Free
get_permit_details	GET /v1/permits/{num_pa}	Free
fuzzy_search_addresses	GET /v1/search?q=text (pg_trgm fuzzy)	Free
find_dvf_neighbors	GET /v1/permits/{num_pa}/dvf (12 ans : Cerema DVF+ 2014-2020 fusionné Geo-DVF 2021-2025)	Pro
get_mdb_score	GET /v1/permits/{num_pa}/score (Score MDB v0.3, 11 signaux)	Pro
get_score_explanation	GET /v1/permits/{num_pa}/score/explain (11 signaux décryptés + interprétation FR contextualisée + top drivers/drags + inputs concrets, USP transparence)	Pro
get_plu_zoning	GET /v1/permits/{num_pa}/plu	Pro
get_risks	GET /v1/permits/{num_pa}/risks (Géorisques BRGM)	Pro
get_parcelle_geometry	GET /v1/permits/{num_pa}/parcelle (cadastre DGFiP)	Pro
get_existing_buildings	GET /v1/permits/{num_pa}/batiments-existants (terrain nu vs bâti, use case MDB)	Pro
get_parcelle_by_id	GET /v1/parcelles/{id_parcelle} (lookup direct cadastre 14 chars Etalab)	Pro
get_neighbor_parcels	GET /v1/permits/{num_pa}/parcelles-voisines (rayon 10-2000 m, killer feature MDB)	Pro
search_permits_in_polygon	POST /v1/permits/inside-polygon (polygon GeoJSON custom ZAC)	Business
get_commune_density_stats	GET /v1/stats/commune/{code}/density (BI agrégé parcelles + bâtiments + permits)	Business
get_permit_full_view	GET /v1/permits/{num_pa}/360 (composite 6-en-1)	Pro
bulk_enrich_list	POST /v1/permits/bulk-enrich (croise liste client jusqu'à 1 000 lignes)	Business
get_economics	GET /v1/permits/{num_pa}/economics (budget chantier : fourchette EUR + scénario + breakdown_by_lot Capeb / FFB + INSEE ICP-BT)	Pro
get_contractors	GET /v1/permits/{num_pa}/contractors (entreprises BTP locales SIRENE NAF 41/42/43, filtres rayon / métier / effectif)	Pro

Sécurité

• La clé API reste côté user (env var locale, jamais transmise au LLM)
• Le LLM voit uniquement les arguments des tools (pas la clé)
• Validation stricte des inputs (regex sur num_pa, ranges Pydantic)
• 16 outils en consultation pure (GET) + 2 outils POST (bulk_enrich_list qui croise une liste client, et search_permits_in_polygon qui prend un polygon GeoJSON custom). Tous en lecture seule côté PermisAPI : aucune donnée client n'est stockée, on renvoie juste les permits qui matchent.

Troubleshooting

pip install permisapi-mcp dit "package introuvable" ou "no matching distribution"

Cause la plus fréquente : votre Python est plus ancien que 3.10. Le MCP SDK Anthropic requiert Python 3.10 minimum, on ne peut pas descendre cette borne.

Vérifiez :

python --version       # ou python3 --version

Si < 3.10, deux solutions au choix.

Solution A (recommandée, 30 secondes) : uvx avec pin Python

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

# 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 config Claude Desktop, remplacez "command": "permisapi-mcp" par :

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

Solution B : upgrade Python système

• macOS : brew install [email protected]
• Windows : télécharger https://www.python.org/downloads/ et cocher "Add to PATH"
• Linux : sudo apt install python3.11 (ou équivalent distro)

Puis pip3.11 install permisapi-mcp.

Guide setup complet + autres FAQ : https://permisapi.fr/mcp

Licence

MIT.

Support

[email protected] : réponse 24-48h sur les plans Pro+, 24-72h sur les autres.

Code source

github.com/Evan-Crx/permisapi-mcp