mcp-datagouv 🇫🇷

Serveur MCP (Model Context Protocol) pour interroger les Open Data de data.gouv.fr, la plateforme ouverte des données publiques françaises.

v2.0 — Cache, retry, rate limiting, agrégations, API Geo, API Adresse, prompts guidés, transport HTTP.

Fonctionnalités

📊 Catalogue data.gouv.fr (20 outils)

| Outil | Description | |-------|-------------| | search_datasets | Recherche par mots-clés, tags, organisation, licence, badge | | get_dataset | Détail complet d'un dataset | | list_dataset_resources | Fichiers/ressources d'un dataset | | get_resource | Détail d'une ressource | | download_resource_preview | Aperçu du contenu d'un fichier (CSV, JSON, texte) | | search_organizations | Recherche d'organisations | | get_organization | Détail d'une organisation | | list_organization_datasets | Datasets d'une organisation | | search_reuses | Réutilisations de données | | get_tabular_meta | Métadonnées tabulaires (colonnes, types) | | query_tabular_data | Requête de données avec recherche textuelle | | query_tabular_data_filtered | Requête avec filtres sur colonnes | | aggregate_tabular_data | Statistiques (sum, avg, min, max, count, distinct) | | group_by_tabular_data | GROUP BY + agrégation | | list_licenses | Licences disponibles | | list_frequencies | Fréquences de mise à jour | | search_tags | Tags/thématiques | | cache_stats | Statistiques du cache | | cache_clear | Vider le cache |

🗺️ API Geo — Découpage administratif (5 outils)

| Outil | Description | |-------|-------------| | search_communes | Recherche par nom, code postal, département, GPS | | get_commune | Détail d'une commune par code INSEE | | list_departements | Liste des départements | | get_departement_communes | Communes d'un département | | list_regions | Liste des régions |

📍 API Adresse — Géocodage (2 outils)

| Outil | Description | |-------|-------------| | geocode_address | Adresse → coordonnées GPS | | reverse_geocode | Coordonnées GPS → adresse |

💬 Prompts prédéfinis (5 prompts)

| Prompt | Description | |--------|-------------| | analyse_dataset | Workflow guidé : recherche → inspection → stats → synthèse | | explorer_organisation | Explorer une organisation en profondeur | | trouver_donnees_territoire | Trouver des données sur un territoire | | comparer_datasets | Comparer deux jeux de données | | geocoder_adresses | Géocoder une liste d'adresses |

📦 Resources MCP (3 resources)

| Resource | Description | |----------|-------------| | datagouv://platform-info | Documentation des APIs disponibles | | datagouv://server-config | Configuration active du serveur | | datagouv://recent-datasets | Datasets consultés durant la session |

Installation

git clone <votre-repo>
cd mcp-datagouv
npm install
npm run build

Configuration

Copiez .env.example en .env et ajustez les variables :

cp .env.example .env

Variables principales :

| Variable | Défaut | Description | |----------|--------|-------------| | DATAGOUV_API_KEY | — | Clé API (optionnel, pour écriture) | | MCP_TRANSPORT | stdio | Transport : stdio ou http | | MCP_HTTP_PORT | 3000 | Port HTTP | | MCP_LOG_LEVEL | info | Niveau de log | | MCP_CACHE_TTL | 300000 | Cache TTL par défaut (5 min) | | MCP_CACHE_TTL_REF | 21600000 | Cache TTL référentiels (6h) | | MCP_MAX_RETRIES | 3 | Retries sur erreurs transitoires | | MCP_ENABLE_GEO | true | Module Geo | | MCP_ENABLE_ADRESSE | true | Module Adresse | | MCP_TABULAR_RATE_LIMIT | 80 | Rate limit API tabulaire (req/s) | | MCP_CATALOG_RATE_LIMIT | 30 | Rate limit API catalogue (req/s) |

Usage

Claude Desktop

Fichier claude_desktop_config.json :

{
  "mcpServers": {
    "datagouv": {
      "command": "node",
      "args": ["/chemin/absolu/vers/mcp-datagouv/build/index.js"],
      "env": {
        "MCP_LOG_LEVEL": "debug"
      }
    }
  }
}

Claude Code

claude mcp add datagouv node /chemin/absolu/vers/mcp-datagouv/build/index.js

Transport HTTP (serveur distant)

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npm start

Docker

docker build -t mcp-datagouv .
docker run -p 3000:3000 mcp-datagouv

Exemples d'utilisation

"Recherche les données sur la qualité de l'air en Île-de-France"
"Montre-moi les datasets du Ministère de l'Intérieur"
"Quels sont les fichiers du dataset des prix du carburant ?"
"Affiche les premières lignes de ce CSV"
"Calcule la moyenne et le max de la colonne 'population'"
"Groupe les données par département et calcule la somme des habitants"
"Géocode l'adresse '8 bd du Port, Amiens'"
"Quelles communes se trouvent dans le département 59 ?"
"Liste les régions de France"

Avec les prompts : `` "Utilise le prompt 'analyse_dataset' sur le sujet 'transport ferroviaire'" "Utilise 'trouver_donnees_territoire' pour Lyon, thématique environnement" ``

Robustesse

Cache mémoire avec TTL configurable (5 min données, 6h référentiels)
Retry automatique avec backoff exponentiel sur erreurs 429/5xx
Rate limiting par domaine API (catalogue, tabulaire, geo, adresse)
Timeout configurable avec abort
Logging structuré sur stderr (compatible STDIO)

Architecture

src/
├── index.ts              # Point d'entrée, transport STDIO/HTTP
├── config.ts             # Configuration via env
├── logger.ts             # Logger structuré (stderr)
├── cache.ts              # Cache mémoire TTL
├── rate-limiter.ts       # Rate limiter sliding window
├── http-client.ts        # Client HTTP (retry, cache, rate limit)
├── api-client.ts         # API data.gouv.fr (catalogue + tabulaire)
├── api-geo.ts            # API Découpage Administratif
├── api-adresse.ts        # API Adresse (géocodage)
├── formatters.ts         # Formatage des réponses
├── aggregations.ts       # Calculs statistiques
├── tools.ts              # Outils MCP catalogue
├── tools-geo.ts          # Outils MCP geo
├── tools-adresse.ts      # Outils MCP adresse
├── prompts.ts            # Prompts MCP prédéfinis
├── resources.ts          # Resources MCP dynamiques
└── __tests__/            # Tests unitaires
    ├── cache.test.ts
    ├── rate-limiter.test.ts
    ├── formatters.test.ts
    └── aggregations.test.ts

Tests

# Tests avec Node.js >= 22 (strip-types natif)
npm test

# Ou après compilation
npm run test:build

APIs utilisées

| API | URL | Authentification | |-----|-----|------------------| | Catalogue data.gouv.fr | https://www.data.gouv.fr/api/1/ | Non (lecture) | | API Tabulaire (beta) | https://tabular-api.data.gouv.fr/api/ | Non | | API Geo | https://geo.api.gouv.fr/ | Non | | API Adresse | https://api-adresse.data.gouv.fr/ | Non |

Licence

MIT

mcp-datagouv