Metadata-Version: 2.5
Name: permisapi-mcp
Version: 0.5.11
Summary: Serveur MCP pour PermisAPI : 18 outils en lecture seule pour interroger 1,3 million de permis de construire en France (depuis 2013) depuis Claude, ChatGPT, Claude Desktop, Cursor, Windsurf et tout client MCP. v0.5.11 : serveur hébergé avec connexion OAuth (inscription dynamique et Client ID Metadata Document, jetons en base), compte Gratuit créable depuis la page d'autorisation, descriptions d'outils sobres et factuelles, aucune clé ni jeton dans les journaux.
Project-URL: Homepage, https://permisapi.fr/mcp
Project-URL: Documentation, https://permisapi.fr/mcp
Project-URL: Setup, https://github.com/Evan-Crx/permisapi-mcp/blob/main/README.md
Project-URL: Source, https://github.com/Evan-Crx/permisapi-mcp
Project-URL: Issues, https://github.com/Evan-Crx/permisapi-mcp/issues
Author-email: Evan Caroux <evan@permisapi.fr>
License: MIT
Keywords: anthropic,chatgpt,claude,construire,france,mcp,permis,real-estate,sitadel
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: French
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp>=1.10.0
Requires-Dist: permisapi-client>=0.7.2
Requires-Dist: posthog>=3.7.0
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.19; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Provides-Extra: sse
Requires-Dist: asyncpg>=0.29; extra == 'sse'
Requires-Dist: sqlalchemy[asyncio]<2.1,>=2.0.25; extra == 'sse'
Requires-Dist: starlette>=0.40; extra == 'sse'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'sse'
Description-Content-Type: text/markdown

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