McpDiffusion MCP server
Commit Oct 26, 2026Exposes INSEE French national statistical data to LLMs through a single Model Context Protocol endpoint.
Also known as InseeFrLab/McpDiffusion
- Stars
- 2
- Tools
- 9
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 26, 2026
- License
- Apache-2.0
What is McpDiffusion MCP?
McpDiffusion exposes INSEE French national statistical data to LLMs through a single Model Context Protocol endpoint. It exposes 9 tools, such as get_insee_homepage, search_insee_documents, get_insee_document.
Summary generated from the project's README
About McpDiffusion MCP server
Accessing French national statistical data from within an AI assistant is what McpDiffusion enables. This server provides a single Model Context Protocol endpoint that connects large language models to three distinct INSEE data sources: RMES for semantic ontologies, MELODI for dataset catalogues and observations, and direct INSEE website scraping for official publications and key indicators.
Developers can deploy this server locally using Python or via Docker, connecting it to clients like Claude Desktop, Claude Code, Cursor, or VS Code Continue through HTTP transport. While the RMES tool functions independently, most other tools require a running Elasticsearch instance to access the MELODI and INSEEFR datasets. Users should note that the current data consists of static snapshots synchronized as of July 2026 and is not updated in real time.
By integrating tools such as get_insee_homepage, search_melodi_datasets, and RMES_run_sparql, an AI client can perform complex tasks ranging from retrieving inflation figures to executing SPARQL queries against semantic graphs.
What you can do with it
- 1Retrieve economic indicatorsAsk an AI to find the latest inflation or unemployment rates from the official INSEE homepage.
- 2Explore statistical datasetsUse natural language to search for specific datasets within the Melodi catalogue.
- 3Query semantic definitionsExecute SPARQL queries to explore concept definitions and classification hierarchies in the INSEE semantic database.
- 4Fetch specific observationsRequest filtered numeric observations and attributes from a specific dataset.
Written from the project's README. Every use case is checked against a quote from it.
McpDiffusion MCP tools 9
Detected from the READMEget_insee_homepagesearch_insee_documentsget_insee_documentsearch_insee_conjoncturesearch_insee_chiffreclefsearch_melodi_datasetssearch_melodi_modalitiesget_melodi_observationssend_feedback
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableinseefrlab/mcpdiffusion is public and reachablegithub.com/inseefrlab/mcpdiffusion ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-26github.com/inseefrlab/mcpdiffusion ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMcpDiffusion
⚠️ BETA – NOT PRODUCTION READY
This project is still in beta. It should not be considered a finished or officially‑supported product from INSEE.
⚠️ DATA STALENESS
The underlying databases are static snapshots that were last synchronized in July 2026. They are not kept in real‑time sync with INSEE’s databases
MCPDiffusion is a MCP server that exposes INSEE (French National Institute of Statistics and Economic Studies) public data to Large Language Models. It combines three INSEE data sources behind a single Model Context Protocol endpoint so that an LLM client can discover and call them as native tools.
Server’s URL: https://mcpdiffusion.lab.sspcloud.fr/mcp
En français
⚠️ BÊTA – NE PAS UTILISER EN PRODUCTION
Ce projet est encore en phase bêta. Il ne doit pas être considéré comme un produit fini ou officiellement supporté par l’INSEE.
⚠️ DONNÉES NON À JOUR
Les bases de données sont des instantanés figés dont la dernière synchronisation date de juillet 2026. Elles ne sont pas synchronisées en temps réel avec les bases de données de l’INSEE
MCPDiffusion est un serveur MCP qui met à disposition de modèles de langage (LLM) les données publiques de l’INSEE (Institut national de la statistique et des études économiques). Il regroupe trois sources de données de l’INSEE derrière un unique point d’accès Model Context Protocol, de sorte qu’un client LLM puisse les découvrir et les invoquer comme des outils natifs.
URL du serveur : https://mcpdiffusion.lab.sspcloud.fr/mcp
Table of Contents
- Features
- Data Sources
- Architecture
- Available Tools
- LLM Usage Guide
- Prerequisites
- Installation
- Configuration
- Running the Server
- Connecting an MCP Client
- Project Structure
- Limitations
- Security Notice
- Contributing
- License
Features
- A single MCP endpoint exposing INSEE publications, datasets and concept definitions.
- Tools auto-registered through FastMCP.
- HTTP transport (default port
8000) compatible with any MCP-capable client. - Docker image published automatically on every push to
main. - Structured logging (
mcp.main,mcp.tools) and per-tool call tracing.
Data Sources
| Source | Type | Purpose |
|---|---|---|
| RMES | SPARQL endpoint at https://rdf.insee.fr/sparql |
INSEE statistical ontology: vocabulary, concept definitions (SKOS/XKOS). Works without any local dependency. |
| MELODI | REST API + ElasticSearch index | INSEE data catalogue: search datasets, list columns, fetch filtered observations. |
| insee.fr | HTTP scraping | Official INSEE publications, Informations rapides, and the homepage key indicators. |
External references:
- Publications: https://www.insee.fr/en/statistiques
- Datasets: https://catalogue-donnees.insee.fr/en/catalogue/recherche
- Definitions: https://www.insee.fr/en/metadonnees/definitions
Architecture
┌──────────────────────────┐
│ MCP client │
│ (Claude Code, Cursor, │
│ VS Code, …) │
└────────────┬─────────────┘
│ MCP / HTTP (port 8000)
▼
┌──────────────────────────────────────────────┐
│ FastMCP server (mcpdiffusion/server.py) │
│ ┌────────────────────────────────────────┐ │
│ │ tools/__init__.py — register_tools() │ │
│ └────────────────────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ INSEEFR │ │ MELODI │ │ RMES │ │
│ │ _* │ │ _* │ │ _* │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└────────┼──────────────┼──────────────┼───────┘
│ │ │
│ │ ▼
│ │ ┌─────────────────┐
│ │ │ rdf.insee.fr │
│ │ │ (SPARQL) │
│ │ └─────────────────┘
▼ ▼
┌────────────┐ ┌────────────┐
│ insee.fr │ │ Elastic │
│ (HTTP) │ │ Search │
└────────────┘ └────────────┘
The server boots, loads environment variables, calls register_tools(mcp) to attach every tool exposed in mcpdiffusion/tools/, and then runs the FastMCP HTTP application under Uvicorn.
Available Tools
| Tool | Source | Description |
|---|---|---|
get_insee_homepage |
insee.fr | Retrieve the latest key indicators published on the INSEE homepage (inflation, unemployment, GDP, …). Prefer this for generic, up-to-date questions. |
search_insee_documents |
insee.fr | Search the INSEE catalogue of detailed publications (Insee Première, Insee Analyses, Dossiers, Références, Chiffres-clés, …). |
get_insee_document |
insee.fr | Fetch and parse a specific INSEE publication from a known URL (/fr/statistiques/<id>). |
search_insee_conjoncture |
insee.fr | Search the Informations rapides (rapid releases) index by topic, date and geography. |
search_insee_chiffreclef |
insee.fr | Search key figures and synthetic statistics (population, regional comparisons, simple factual questions). |
search_melodi_datasets |
MELODI | Search the Melodi dataset catalogue with a natural-language French query. |
search_melodi_modalities |
MELODI | Given a dataset and column identifiers, rank the most relevant modality codes/labels for a free-text query. |
get_melodi_observations |
MELODI | Retrieve filtered observations from a Melodi dataset (dimensions, attributes, numeric measure with unit). |
RMES_list_graphs |
RMES | List available named graphs in the INSEE semantic database, grouped by category (nomenclatures, concepts, operations, …). Use this first to discover the graph structure. |
RMES_describe_resource |
RMES | Retrieve all properties (predicate → value) of a specific RDF resource identified by its URI. Useful for exploring concept definitions or classification hierarchies. |
RMES_run_sparql |
RMES | Run a SPARQL query against the INSEE semantic graph (concept definitions, code lists, metadata). The only tool that works without an Elasticsearch instance. |
send_feedback |
Extras | Submit structured feedback about tool behavior, bugs, or suggestions for improvement. Appends timestamped entries to the feedback log. |
LLM Usage Guide
For detailed guidance on how to effectively use these tools as a Large Language Model, see SKILL.md. It includes:
- Tool selection decision trees
- Workflow patterns for each data source
- Common pitfalls and how to avoid them
- SPARQL query templates
- MELODI three-step workflow (search → modalities → observations)
The skill file is designed to be loaded into your context when working with INSEE data through this MCP server.
Prerequisites
- Python 3.12 (matches the Dockerfile base image)
- A running Elasticsearch instance reachable from the server (required for all
MELODI_*andINSEEFR_*tools) - Internet access to
insee.frandrdf.insee.fr - (Optional) Docker if you want to run the server in a container
Without Elasticsearch, only
RMES_run_sparqlis functional.
Installation
1. Clone the repository
git clone https://github.com/InseeFrLab/McpDiffusion.git
cd mcp_diffusion
2. Configure environment
cp mcpdiffusion/.env.example mcpdiffusion/.env
# then edit mcpdiffusion/.env (see Configuration)
3. Install dependencies
uv sync
4. (Alternative) Build the Docker image
docker build -t mcp-insee .
Configuration
All settings live in mcpdiffusion/.env:
| Variable | Default | Description |
|---|---|---|
MCP_HOST |
0.0.0.0 |
Bind address. Use 127.0.0.1 for local development. |
MCP_PORT |
8000 |
HTTP port the FastMCP server listens on. |
ES_HOST |
http://elasticsearch:9200 |
Elasticsearch URL when running in Docker. |
ES_HOST_LOCAL |
http://localhost:9200 |
Elasticsearch URL when running on the host. |
Additional optional variable: LOG_LEVEL (default INFO).
Running the Server
Local
python3 mcpdiffusion/server.py
The server listens on http://$MCP_HOST:$MCP_PORT (defaults to http://0.0.0.0:8000).
Docker
docker run --rm \
-p 8000:8000 \
--env-file mcpdiffusion/.env \
mcp-insee
Health check:
curl -i http://localhost:8000/
Connecting an MCP Client
The server speaks MCP over HTTP. Any MCP-compatible client can be pointed at it. Below are examples for the most common clients.
Claude Code (CLI)
Add the server globally:
claude mcp add --transport http mcp-insee http://localhost:8000
…or per-project, in .mcp.json at the repository root:
{
"mcpServers": {
"mcp-insee": {
"type": "http",
"url": "http://localhost:8000"
}
}
}
Then start a Claude Code session in this directory. The tools listed in Available Tools will appear automatically.
Claude Desktop
Edit claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"mcp-insee": {
"type": "http",
"url": "http://localhost:8000"
}
}
}
Restart Claude Desktop; the tools will be available under the 🔌 menu.
Other MCP clients (Cursor, VS Code Continue, …)
Any client supporting the MCP HTTP transport can be configured the same way:
{
"mcpServers": {
"mcp-insee": {
"url": "http://localhost:8000"
}
}
}
Project Structure
mcp_diffusion/
├── Dockerfile
├── README.md
├── LICENSE
└── mcpdiffusion/
├── server.py # FastMCP entrypoint (Uvicorn + register_tools)
├── requirements.txt
├── .env.example
├── helpers/
│ └── logging.py # logging config + @log_tool decorator
└── tools/
├── __init__.py # register_tools(): enable/disable tools here
├── env.py # tool metadata + theme/geo dictionaries
├── INSEEFR_get_homepage.py
├── INSEEFR_search_documents.py
├── INSEEFR_get_documents.py
├── INSEEFR_get_conjoncture.py
├── MELODI_search_dataset.py
├── MELODI_get_columns.py
├── MELODI_get_dataset.py
└── RMES_search_graph.py
Each tool lives in its own file and is registered by tools/__init__.py. To disable a tool, comment out its import and the corresponding call in register_tools().
Limitations
- BETA software. APIs, tool schemas, and configuration may change without notice.
- ElasticSearch is not public. Most tools depend on a private ElasticSearch index. Only
RMES_run_sparqlworks without it. - The RMES tool accepts raw SPARQL — model clients must be capable of generating well-formed queries.
- Tool schemas and category names are currently a mix of French and English (mirrors the INSEE source data).
- The GitHub Actions workflow pushes a Docker image on every push to
main; the image name is configured via theDOCKER_USERNAMErepository variable.
Security Notice
The shipped configuration is intentionally permissive for local testing:
server.pydisables DNS rebinding protection and usesTrustedHostMiddlewarewithallowed_hosts=["*"](flagged with# remove before flight).- Uvicorn is started with
forwarded_allow_ips="*".
Before deploying anywhere reachable from the internet, harden these settings — restrict allowed_hosts, re-enable rebinding protection, and limit forwarded_allow_ips to your reverse proxy.
Contributing
- Fork the repository.
- Create a feature branch (
git checkout -b feat/my-tool). - Add or modify a tool in
mcpdiffusion/tools/(one tool per file). - Register it in
mcpdiffusion/tools/__init__.pyinsideregister_tools(). - Run the server locally and exercise the new tool with an MCP client.
- Open a Pull Request.
Issues and PRs are welcome — this is a BETA project.
License
Released under the Apache License 2.0. See LICENSE for the full text.
McpDiffusion MCP questions
What tools does McpDiffusion MCP provide?
It exposes 9 tools, including get_insee_homepage, search_insee_documents, get_insee_document, search_insee_conjoncture, search_insee_chiffreclef.
Is the data real-time?
No, the underlying databases are static snapshots last synchronized in July 2026 and are not kept in real-time sync.
Can I use this without Elasticsearch?
Yes, but functionality will be limited; only the RMES_run_sparql tool will work without an Elasticsearch instance.