mcp-reunion

MCP server for La Réunion public open data, exposed over stdio for Claude Desktop and other MCP clients.

What it covers

Primary source: the OpenDataSoft Explore v2.1 API at data.regionreunion.com. A small National elections module also queries tabular-api.data.gouv.fr for the 2024 anticipated legislative + European results that the regional portal doesn't carry. Currently 108 tools across 26 modules. A catalog module lets the client reach any of the ~270 datasets at data.regionreunion.com that aren't wired to a dedicated tool yet.

Modules

• Administration — public-admin local counters (annuaire), RNA associations registry, elected officials, 2022 presidential & legislative results per polling station (rounds 1 & 2 for legislative), BOAMP public-procurement notices, QPV priority neighborhoods, baby names since 2000.
• Commune — composite tools that join several datasets in parallel: `reunion_find_commune` (fuzzy resolver to canonical INSEE code), `reunion_commune_profile` (population + QPV + schools + businesses + accidents + museums in one call), `reunion_compare_communes` (side-by-side on 2-5 communes), `reunion_iris_profile` (IRIS metadata + 2014 income/poverty/inequality indicators).
• Culture — Musées de France directory, Joconde collection search, public libraries, festivals, annual museum attendance.
• Economy — SIRENE v3 establishment search, INSEE monthly CPI, FEDER 2014-2020 beneficiaries, coworking spaces, IRIS-level income/poverty indicators.
• Education — middle-school & lycée IPS, Génération 2024 label, Parcoursup programs, geolocated school directory, REP/REP+ priority-education schools, higher-ed enrollment, training orgs/CFA.
• Employment (demandeurs-d-emploi-…-a-la-reunion) — Pôle emploi jobseeker counts by age/sex and by commune.
• Environment — OpenAQ air-quality, household waste tonnage, RGE eco-renovation companies, ZNIEFF protected zones, Parc national perimeters, petroleum-product consumption, water-management points of interest.
• Facilities (base-permanente-des-equipements-geolocalisee-la-reunion, equipements-sportifs) — INSEE BPE facilities and the national sport-equipment inventory, filtered to Réunion.
• Geography (ban-lareunion, bal-la-possession, communes-millesime-france, cantons-millesime-france, intercommunalites-millesime-france, iris-millesime-france, les-20-quartiers-villesaintdenis) — BAN/BAL addresses and the official communes / cantons / EPCI / IRIS / Saint-Denis quarters reference layers.
• Health — CNAM health-professional directory, COVID stats, pathologies, FINESS, Possession health pros.
• Heritage — UNESCO World Heritage perimeters and Outstanding Universal Value criterion-vii contribution areas for La Réunion National Park.
• Hospitality (etablissements-touristiques-lareunion-wssoubik, hebergements-classespublic, localisation-potentielle-ecolodge-lareunion) — tourism establishments, classified accommodations, ecolodge zones.
• Insights — high-level composite dashboards for public services by commune and tourism.
• National elections (tabular-api.data.gouv.fr — Ministère de l'Intérieur) — 2024 anticipated legislative results (rounds 1 & 2) per Réunion circonscription, and 2024 European results aggregated for département 974. Complements the 2022 results carried by the regional portal.
• Nearby — radius-based search around coordinates for schools, Car Jaune stops, and official museums.
• Housing (logements-et-logements-sociaux-…, couts-et-surfaces-moyens-…) — departmental housing atlas and social-housing costs.
• Possession (donnees-essentielles-marches-publics-…, subventions-attribuees-…) — La Possession public procurement contracts and association grants.
• Router — reunion_find_relevant_tools, a deterministic helper that maps natural-language questions to likely tools, datasets, and query flows.
• Social — CAF beneficiaries and prestation amounts, childcare facilities (Saint-Denis + Possession).
• Telecom (sites-mobiles-5g-a-la-reunion, arcep_regions) — 5G cell sites per operator and FttH deployment coverage.
• Territory — DVF real-estate transactions, INSEE commune population, La Poste postal codes, potentiel foncier land reserves, Sitadel residential construction permits.
• Tourism — family trails, canyoning routes, SIT Soubik landmarks & cultural POIs, hiking circuits, coastal trail, pools, monthly tourism frequentation since 2017.
• Transport — TMJA road traffic, functional road classification, Car Jaune GTFS stops/routes and planning context, regional cycle network, road accidents (2016-2019), vehicle technical-inspection prices, daily flow & speed limits on national roads.
• Urbanism (base-permanente-des-plu-de-la-reunion, liste-des-permis-de-constuire-…) — PLU zoning and non-residential building permits (Sitadel).
• Weather (donnees-synop-essentielles-ommpublic) — Météo France SYNOP observations for Réunion stations: temperature, humidity, wind, pressure, rainfall; plus a station-listing tool.
• Catalog (meta) — search_catalog, inspect_dataset, query_dataset. Lets the agent discover and query any of the ~270 datasets not covered by a dedicated module, with a raw ODSQL where clause as escape hatch.
• Resources — static MCP resources for commune, EPCI, IRIS, catalog, and popular dataset reference data.

The data.regionreunion.com catalog exposes ~270 datasets. More modules can be added incrementally — see Extending below.

For a generated module-by-module view of dataset and tool coverage, see COVERAGE.md.

Reaching datasets that aren't wired yet

The dedicated modules above cover the most-asked topics, but the portal has ~270 datasets in total. Instead of writing a new module for every long-tail question, the catalog module gives the MCP client three generic tools that together act as an escape hatch onto the whole portal:

1. reunion_search_catalog — keyword / theme / publisher search across all datasets. Returns dataset IDs, titles, descriptions, record counts.
2. reunion_inspect_dataset — given a dataset ID, returns its full schema (field names + types) so the agent knows what it can filter on.
3. reunion_query_dataset — fetches records from any dataset with a raw ODSQL where clause, select, order_by, limit.

Typical flow when the user asks about something no dedicated module covers (e.g. volcanology, elections, library attendance, …):

reunion_search_catalog({ query: "volcan" })
  → returns e.g. dataset_id "suivi-volcanologique-piton-fournaise"
reunion_inspect_dataset({ dataset_id: "suivi-volcanologique-piton-fournaise" })
  → returns fields like date, type_evenement, magnitude, profondeur…
reunion_query_dataset({
  dataset_id: "suivi-volcanologique-piton-fournaise",
  where: "type_evenement = 'éruption' AND date >= date'2023-01-01'",
  order_by: "date DESC",
  limit: 20
})

Net effect: the agent can answer questions backed by any of the ~270 datasets without anyone having to code a new module first. Datasets that turn out to be popular via query_dataset are candidates for being promoted into their own dedicated module with curated field names.

Install

npm install
npm run build
npm test
npm run dev

Claude Desktop

{
  "mcpServers": {
    "reunion": {
      "command": "npx",
      "args": ["mcp-reunion"]
    }
  }
}

Examples

Prompt recipes live in examples/:

• claude-desktop.md — setup and first prompts
• civic-analysis.md — commune and procurement analysis
• elections.md — 2022 and 2024 election analysis
• tourism.md — tourism and outdoor activity prompts
• transport.md — road and transit prompts

MCP resources

The server also exposes reference resources:

• reunion://communes
• reunion://epci
• reunion://iris
• reunion://datasets/catalog
• reunion://datasets/popular

Extending

Each module lives in src/modules/ and wires an OpenDataSoft dataset to one or more MCP tools via the shared ReunionClient (src/client.ts). To add a module:

1. Identify the dataset ID at https://data.regionreunion.com/api/explore/v2.1/catalog/datasets?limit=100.
2. Inspect its fields (/catalog/datasets/<id>) to know what to expose.
3. Write a module following the pattern in src/modules/weather.ts or transport.ts.
4. Register it in src/modules/index.ts and bump TOOL_COUNT.

Production notes

• Runtime: Node.js 20+
• Transport: stdio
• Upstream API: https://data.regionreunion.com/api/explore/v2.1
• Authentication: none
• Language of source data: mostly French

Maintenance checks

• npm run check:schema verifies high-value upstream dataset fields listed in schema-expectations.json.
• npm run docs:coverage regenerates COVERAGE.md.
• Output conventions are documented in docs/output-contracts.md.
• Release automation is documented in docs/release.md.

Optional local telemetry

Tool-call telemetry is disabled by default. To debug local usage patterns without sending anything to a remote service:

MCP_REUNION_TELEMETRY=local npx -y mcp-reunion

This writes JSONL records to .mcp-reunion-telemetry.jsonl by default. Override the path with MCP_REUNION_TELEMETRY_PATH.

License