julienkalamon/ign-apicarto-mcp-server

IGN API Carto MCP Server

Serveur MCP (Model Context Protocol) pour interroger les données géographiques françaises via l'API Carto de l'IGN

📋 Table des matières

• À propos
• Fonctionnalités
• Prérequis
• Installation
• Configuration
• Utilisation
• Projets réalisés
• Exemples détaillés
• Format des géométries
• Limitations
• Sources de données
• Développement
• Dépannage
• Ressources
• Licence

À propos

Ce serveur MCP permet d'accéder aux riches données géographiques de l'IGN (Institut national de l'information géographique et forestière) directement depuis Claude Desktop ou tout autre client compatible MCP.

Il expose les principales API de l'écosystème IGN API Carto, permettant d'interroger des données cadastrales, agricoles, environnementales, d'urbanisme et administratives françaises en langage naturel.

Cas d'usage

• 🏘️ Analyser des données cadastrales et parcellaires
• 🌾 Consulter les déclarations agricoles (RPG)
• 🌳 Identifier les zones naturelles protégées
• 🏗️ Vérifier les règlements d'urbanisme (PLU, GPU)
• 🍷 Localiser les appellations viticoles
• 🗺️ Obtenir des données administratives géolocalisées

Fonctionnalités

Outils disponibles

Prérequis

• Node.js 16+ et npm
• Claude Desktop ou un client MCP compatible
• Connexion internet pour accéder aux API IGN

Installation

1. Cloner le dépôt

git clone https://github.com/votre-utilisateur/ign-apicarto-mcp-server.git
cd ign-apicarto-mcp-server

2. Installer les dépendances

npm install

3. Configurer les variables d'environnement

# Copier le fichier d'exemple
cp .env.example .env.local

Éditez .env.local et ajoutez votre clé API IGN si vous souhaitez utiliser l'endpoint AOC viticoles :

# Obtenir une clé gratuite : https://geoservices.ign.fr/
IGN_API_KEY=votre_cle_api

4. Compiler le projet

npm run build

Le serveur compilé sera disponible dans le dossier dist/.

Configuration

Configurez ce serveur MCP avec votre client IA préféré. Cliquez sur le client que vous utilisez pour voir les instructions détaillées.

{
  "mcpServers": {
    "ign-apicarto": {
      "command": "node",
      "args": ["/chemin/absolu/vers/ign-apicarto-mcp-server/dist/index.js"]
    }
  }
}

{
  "mcpServers": {
    "ign-apicarto": {
      "command": "node",
      "args": ["/chemin/absolu/vers/ign-apicarto-mcp-server/dist/index.js"]
    }
  }
}

{
  "enableAllProjectMcpServers": true
}

{
  "enabledMcpjsonServers": ["ign-apicarto"]
}

{
  "mcpServers": {
    "ign-apicarto": {
      "command": "node",
      "args": ["/chemin/absolu/vers/ign-apicarto-mcp-server/dist/index.js"]
    }
  }
}

{
  "mcpServers": {
    "ign-apicarto": {
      "command": "node",
      "args": ["${workspaceFolder}/ign-apicarto-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "ign-apicarto": {
      "command": "node",
      "args": ["/chemin/absolu/vers/ign-apicarto-mcp-server/dist/index.js"]
    }
  }
}

{
  "mcpServers": {
    "ign-apicarto": {
      "command": "node",
      "args": ["/chemin/absolu/vers/ign-apicarto-mcp-server/dist/index.js"]
    }
  }
}

{
  "mcpServers": {
    "ign-apicarto": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

TRANSPORT=http PORT=3000 npm start

Modes de transport

Le serveur supporte deux modes de communication :

Mode stdio (par défaut)

Mode standard pour une utilisation locale avec Claude Desktop :

npm start

Mode HTTP (optionnel)

Pour une utilisation en réseau ou depuis un client distant :

TRANSPORT=http PORT=3000 npm start

Variables d'environnement

Configurez le serveur via le fichier .env.local ou directement en ligne de commande :

Fichiers de configuration :

• .env.example : Template avec toutes les variables disponibles
• .env.local : Votre configuration locale (non versionné)

Utilisation

Une fois configuré dans Claude Desktop, vous pouvez interroger les données IGN en langage naturel. Le serveur traduira automatiquement vos requêtes en appels API appropriés.

Redémarrage après configuration

Après avoir modifié claude_desktop_config.json, redémarrez Claude Desktop pour que les changements soient pris en compte.

Projets réalisés

🍷 Analyse Territoriale de Margaux-Cantenac

Application interactive d'analyse territoriale pour la commune viticole de Margaux-Cantenac (Gironde), développée avec Claude et ce serveur MCP.

🔗 Voir la démo interactive

Fonctionnalités

L'application offre une analyse complète du territoire en 4 volets :

Technologies

• Interface React avec navigation par onglets
• Intégration de données IGN et INPN (Muséum National d'Histoire Naturelle)
• Visualisation géographique (bounding box, coordonnées précises)
• Codes couleur pour différencier les types de zones territoriales

Comment le reproduire ?

Créé une application React interactive pour analyser le territoire de la commune
de Margaux-Cantenac. Utilise les données IGN pour afficher :
- Les informations administratives
- Le zonage PLU complet
- Les zones naturelles protégées
- Les sections cadastrales

L'interface doit être organisée en onglets avec une navigation fluide.

💡 Vous avez créé un projet avec ce serveur MCP ? Partagez-le en ouvrant une issue GitHub !

Exemples détaillés

1. Recherche par code postal

Question :

Quelles communes sont associées au code postal 75001 ?

Réponse attendue :

• Liste des communes avec code INSEE
• Coordonnées géographiques
• Limites administratives

Outil utilisé : ign_get_communes_by_postal_code

2. Recherche de parcelles cadastrales

Question :

Trouve les parcelles cadastrales de la commune avec le code INSEE 75101

Paramètres possibles :

• Code INSEE de la commune
• Section cadastrale
• Numéro de parcelle

Outil utilisé : ign_get_cadastre_parcelles

3. Vérification du zonage d'urbanisme

Question :

Quel est le zonage PLU à ces coordonnées : {"type":"Point","coordinates":[2.35,48.85]} ?

Informations retournées :

• Type de zone (U, AU, A, N)
• Règlement d'urbanisme applicable
• Restrictions de constructibilité
• Date de mise à jour du PLU

Outil utilisé : ign_get_gpu_urbanisme

4. Zones naturelles protégées

Question :

Y a-t-il des zones Natura 2000 à proximité de ce point : {"type":"Point","coordinates":[-1.69,48.10]} ?

Types de zones retournées :

• Sites Natura 2000 (ZSC, ZPS)
• ZNIEFF (type I et II)
• Parcs Nationaux et Régionaux
• Réserves naturelles

Outil utilisé : ign_get_nature_areas

5. Registre Parcellaire Graphique (agriculture)

Question :

Quelles cultures sont déclarées sur cette parcelle agricole en 2023 ?
Géométrie : {"type":"Point","coordinates":[2.35,45.85]}

Données disponibles :

• Type de culture
• Surface déclarée
• Code culture PAC
• Année de déclaration (2010-2024)

Outil utilisé : ign_get_rpg

6. Appellations viticoles

Note : Cet endpoint nécessite une clé API IGN gratuite. Obtenez-la sur geoservices.ign.fr

Question :

Cette parcelle est-elle située dans une AOC viticole ?
Coordonnées : {"type":"Point","coordinates":[4.84,45.76]}

Informations retournées :

• Type d'appellation (AOC, IGP, VSIG)
• Nom de l'appellation
• Identifiant de l'appellation
• Géométrie de la zone

Outil utilisé : ign_get_aoc_viticoles

Configuration requise :

# Dans .env.local
IGN_API_KEY=votre_cle_api

7. Limites administratives

Question :

Dans quel département et quelle région se trouve la commune de Lyon ?

Données disponibles :

• Limites communales
• Contours départementaux
• Contours régionaux
• Codes officiels géographiques

Outil utilisé : ign_get_administrative_limits

Format des géométries

Les géométries doivent être au format GeoJSON en WGS84 (EPSG:4326) :

// Point
{"type":"Point","coordinates":[longitude, latitude]}

// Polygon
{"type":"Polygon","coordinates":[[[lon1,lat1],[lon2,lat2],[lon3,lat3],[lon1,lat1]]]}

// MultiPolygon
{"type":"MultiPolygon","coordinates":[[[[lon1,lat1],[lon2,lat2],...]],[...]]}

Limitations

Limites des API IGN

Limitations fonctionnelles

• ⚠️ Le module WFS-Geoportail est en version beta
• Certaines données peuvent avoir un délai de mise à jour
• Les géométries complexes peuvent nécessiter une simplification
• Les données RPG sont disponibles de 2010 à 2024

Sources de données

Développement

Structure du projet

ign-apicarto-mcp-server/
├── src/
│   ├── index.ts          # Point d'entrée du serveur MCP
│   ├── api-client.ts     # Client HTTP pour l'API IGN
│   └── types.ts          # Types TypeScript
├── dist/                 # Fichiers compilés
├── .env.example          # Template des variables d'environnement
├── .env.local            # Configuration locale (non versionné)
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

Scripts disponibles

# Démarrer le serveur en mode développement
npm run dev

# Compiler le projet
npm run build

# Démarrer le serveur en production
npm start

# Lancer les tests (si disponibles)
npm test

# Vérifier le code
npm run lint

Contribuer

Les contributions sont les bienvenues ! Pour contribuer :

1. Forkez le projet
2. Créez une branche pour votre fonctionnalité (git checkout -b feature/AmazingFeature)
3. Committez vos changements (git commit -m 'Add some AmazingFeature')
4. Pushez vers la branche (git push origin feature/AmazingFeature)
5. Ouvrez une Pull Request

Ajouter un nouvel outil

Pour ajouter un nouvel outil MCP :

1. Créez un nouveau fichier dans src/tools/
2. Définissez le schéma de l'outil avec ses paramètres
3. Implémentez la logique d'appel à l'API IGN
4. Enregistrez l'outil dans src/index.ts
5. Documentez l'outil dans ce README

Dépannage

Le serveur ne démarre pas

Vérifications :

• Node.js version 16+ est installé : node --version
• Les dépendances sont installées : npm install
• Le projet est compilé : npm run build
• Le fichier dist/index.js existe

Claude Desktop ne détecte pas le serveur

Solutions :

1. Vérifiez que le chemin dans claude_desktop_config.json est absolu et correct
2. Redémarrez complètement Claude Desktop
3. Vérifiez les logs de Claude Desktop :
   • macOS : ~/Library/Logs/Claude/
   • Windows : %APPDATA%\Claude\logs\
   • Linux : ~/.config/Claude/logs/

Erreurs d'API

Problèmes courants :

Problèmes de géométrie

Les géométries doivent être en WGS84 (EPSG:4326) avec longitude avant latitude :

✅ Correct : {"type":"Point","coordinates":[2.35, 48.85]}
❌ Incorrect : {"type":"Point","coordinates":[48.85, 2.35]}

Performances lentes

Optimisations :

• Utilisez des géométries simplifiées pour les grandes zones
• Limitez le nombre de résultats avec le paramètre _limit
• Utilisez des filtres spécifiques plutôt que des requêtes larges
• Vérifiez votre connexion internet

Ressources

Documentation officielle

• Documentation API Carto - Documentation complète des API
• Géoservices IGN - Portail des géoservices
• Model Context Protocol - Spécification MCP
• Claude Desktop - Application Claude Desktop

Outils utiles

• GeoJSON.io - Créer et visualiser des géométries GeoJSON
• Projections EPSG - Informations sur les systèmes de projection
• Géoportail - Visualiser les données IGN

Communauté

• Issues GitHub - Reporter un bug ou suggérer une fonctionnalité
• Discussions - Poser des questions

Licence

Ce projet est sous licence MIT. Voir le fichier pour plus de détails.

Données IGN

Les données IGN sont soumises à la Licence Ouverte v2.0.

Développé avec ❤️ pour la communauté géospatiale française