README.md

metadata

title: MCP Indicators
emoji: 📉
colorFrom: blue
colorTo: pink
sdk: gradio
sdk_version: 5.29.0
app_file: app.py
pinned: false

MCP Server - Indicateurs Territoriaux de Transition Écologique

Serveur MCP (Model Context Protocol) exposant l'API du Hub d'Indicateurs Territoriaux de Transition Écologique (CGDD/Ministère de la Transition Écologique).

Ce serveur permet à des LLMs (Claude, GPT, etc.) d'interroger les données environnementales territoriales françaises.

Outils MCP disponibles

1. list_indicators

Liste tous les indicateurs avec filtres optionnels.

Paramètres :

• thematique (optionnel) : Filtre par thématique FNV ("mieux se déplacer", "mieux se loger"...)
• maille (optionnel) : Filtre par niveau géographique ("region", "departement", "epci", "commune")

2. get_indicator_details

Retourne les détails complets d'un indicateur (description, méthode de calcul, sources).

Paramètres :

• indicator_id : ID numérique de l'indicateur

3. query_indicator_data

Interroge les données d'un indicateur pour un territoire.

Paramètres :

• indicator_id : ID de l'indicateur
• geographic_level : "region" | "departement" | "epci" | "commune"
• geographic_code (optionnel) : Code INSEE du territoire
• year (optionnel) : Année des données

4. search_indicators

Recherche d'indicateurs par mots-clés.

Paramètres :

• query : Termes de recherche (recherche dans libellé et description)

Installation

Prérequis

• Python >= 3.10
• Un token d'authentification pour l'API Indicateurs

Installation locale

# Cloner le dépôt
git clone https://github.com/your-repo/mcp-indicateurs-te.git
cd mcp-indicateurs-te

# Créer un environnement virtuel
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou: venv\Scripts\activate  # Windows

# Installer les dépendances
pip install -r requirements.txt

# Configurer le token
cp .env.example .env
# Éditer .env et ajouter votre token INDICATEURS_TE_TOKEN

# Lancer le serveur
python app.py

Le serveur sera accessible sur http://localhost:7860.

Déploiement HuggingFace Spaces

1. Créer un nouveau Space avec le SDK Gradio
2. Pousser le code vers le Space
3. Configurer le secret INDICATEURS_TE_TOKEN dans les paramètres du Space

Configuration MCP Client

Claude Desktop

Ajouter dans claude_desktop_config.json :

{
  "mcpServers": {
    "indicateurs-te": {
      "url": "https://YOUR-SPACE.hf.space/gradio_api/mcp/"
    }
  }
}

Cursor

Ajouter dans les paramètres MCP de Cursor :

{
  "mcpServers": {
    "indicateurs-te": {
      "url": "http://localhost:7860/gradio_api/mcp/"
    }
  }
}

Avec mcp-remote (pour clients ne supportant pas HTTP)

{
  "mcpServers": {
    "indicateurs-te": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:7860/gradio_api/mcp/"
      ]
    }
  }
}

Architecture de l'API (validée par tests)

Convention de nommage des cubes

Les cubes de données suivent le format : {thematique}_{maille}

Suffixe	Maille
_com	Commune
_epci	EPCI
_dpt	Département
_reg	Région

Exemples :

• conso_enaf_com → Consommation ENAF, maille commune
• surface_bio_dpt → Surface bio, maille département

Les measures contiennent l'ID de l'indicateur

Format : {cube_name}.id_{indicator_id}

Exemples :

• conso_enaf_com.id_611 → Indicateur 611 dans le cube conso_enaf_com
• surface_bio_dpt.id_606 → Indicateur 606 dans le cube surface_bio_dpt

Dimensions géographiques (standardisées)

Dimension	Description
geocode_commune	Code INSEE commune (5 chiffres)
libelle_commune	Nom de la commune
geocode_epci	Code SIREN EPCI (9 chiffres)
libelle_epci	Nom de l'EPCI
geocode_departement	Code département (2-3 car.)
libelle_departement	Nom du département
geocode_region	Code région (2 chiffres)
libelle_region	Nom de la région

Dimensions temporelles

Dimension	Description
annee	Année (string : "2020")

Exemples d'utilisation

Via un LLM

Utilisateur: Quels indicateurs sur la consommation d'espace ?

LLM: [appelle search_indicators("consommation espace")]
     Voici les indicateurs disponibles :
     - ID 611: Consommation d'espaces naturels, agricoles et forestiers

Utilisateur: Détails sur l'indicateur 611

LLM: [appelle get_indicator_details("611")]
     L'indicateur 611 mesure la consommation d'ENAF...
     Mailles disponibles: commune, epci, departement, region

Utilisateur: Valeurs pour la région PACA en 2020

LLM: [appelle query_indicator_data("611", "region", "93", "2020")]
     Pour PACA (code 93) en 2020 : 1737.29 ha

Exemple de requête Cube.js validée

{
  "query": {
    "measures": ["conso_enaf_com.id_611"],
    "dimensions": [
      "conso_enaf_com.libelle_region",
      "conso_enaf_com.annee"
    ],
    "filters": [
      {
        "member": "conso_enaf_com.geocode_region",
        "operator": "equals",
        "values": ["93"]
      }
    ],
    "limit": 100
  }
}

Codes géographiques INSEE

Niveau	Format	Exemples
Région	2 chiffres	93 (PACA), 11 (Île-de-France), 75 (Nouvelle-Aquitaine), 84 (Auvergne-Rhône-Alpes)
Département	2-3 caractères	13, 2A, 974
EPCI	9 chiffres (SIREN)	200054807
Commune	5 chiffres	75056 (Paris), 13055 (Marseille)

Variables d'environnement

Variable	Description	Défaut
INDICATEURS_TE_TOKEN	Token JWT pour l'API	(requis)
INDICATEURS_TE_BASE_URL	URL de base de l'API	https://api.indicateurs.ecologie.gouv.fr
CACHE_REFRESH_SECONDS	Intervalle de rafraîchissement du cache	3600

Architecture technique

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│   Gradio App     │────▶│   Cube.js API   │
│ (Claude, etc.)  │     │   (MCP Server)   │     │  (Indicateurs)  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                        ┌──────┴──────┐
                        │ CubeResolver │
                        │   + Cache    │
                        └─────────────┘

• Gradio : Interface web + endpoint SSE MCP
• CubeResolver : Mapping indicator_id → cube_name via parsing /meta
• Cache : Métadonnées des indicateurs chargées au démarrage

Structure du projet

├── src/
│   ├── __init__.py          # Package init
│   ├── api_client.py        # Client HTTP Cube.js async
│   ├── cube_resolver.py     # Logique find_cube_for_indicator
│   ├── cache.py             # Cache des métadonnées
│   ├── models.py            # Modèles Pydantic
│   └── tools.py             # Implémentation des 4 outils MCP
├── app.py                   # Point d'entrée Gradio
├── requirements.txt         # Dépendances
└── .env.example             # Template de configuration

Développement

Test avec MCP Inspector

# Lancer le serveur
python app.py

# Dans un autre terminal
npx @modelcontextprotocol/inspector
# Connecter à http://localhost:7860/gradio_api/mcp/

Points d'attention

1. Cache du /meta : ~100+ cubes, chargé une fois au startup
2. Mapping indicator_id → cube : Parcours des measures de chaque cube
3. Mailles non uniformes : Vérifier mailles_disponibles avant de requêter
4. Valeurs string : Les filtres Cube.js attendent des strings ("93" pas 93)

Ressources

• Documentation MCP
• Gradio MCP Guide
• API Cube.js
• Portail Indicateurs

Licence

MIT