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