README.md

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

```bash
# 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` :

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

### Cursor

Ajouter dans les paramètres MCP de Cursor :

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

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

```json
{
  "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

```json
{
  "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

```bash
# 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](https://modelcontextprotocol.io/)
- [Gradio MCP Guide](https://gradio.app/guides/building-mcp-server-with-gradio)
- [API Cube.js](https://cube.dev/docs/rest-api)
- [Portail Indicateurs](https://ecologie.data.gouv.fr/indicators)

## Licence

MIT