istat-mcp-suite
The ISTAT MCP Suite is an MCP server that lets LLM agents search, inspect, and retrieve official Italian statistics from ISTAT via SDMX APIs without dealing with cryptic IDs, huge codelists, or rate-limit/IP-block issues.
Search datasets:
discover_dataflowsfinds ISTAT dataflows by keywords, returning IDs and names.Get dataset structure & codes:
get_constraintsreturns dimension order, key template, and valid codes/labels, with options for dimensions-only or per-dimension lookups.Fetch statistical data:
get_dataextracts data using dotted SDMX keys, supports time filters, last-N observations, inline output for small results, and automatic file download for large datasets.Resolve Italian territories offline:
get_territorial_codesinstantly maps names or codes to 8,039 official REF_AREA codes (comuni, province, regioni, ripartizioni) without network calls.Understand concepts:
get_conceptsexplains SDMX concept IDs like REF_AREA, FREQ, DATA_TYPE.Visualize structures:
get_structure_diagramgenerates Mermaid.js diagrams of dataset dimensions and codelists.Monitor the server:
get_cache_diagnosticsreports cache status, disk usage, and downloaded files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@istat-mcp-suite What is the latest inflation rate in Italy?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ISTAT MCP Suite
Server MCP che espone i dati statistici ufficiali
dell'ISTAT a un agente LLM, attraverso le API SDMX REST di esploradati.istat.it.
L'obiettivo è pratico: le API SDMX dell'ISTAT sono complete ma poco indulgenti — id criptici, chiavi posizionali, codeliste da 12.000 voci, endpoint che a volte non rispondono affatto. Un agente lasciato a interrogarle direttamente spreca token, va in timeout e si fa bloccare l'IP. Questo server si occupa di quella parte.
Indice
Related MCP server: mcp-istat-it
Cosa fa
Ricerca dataset | Cerca fra i ~4.700 dataflow ISTAT per parole chiave, senza doverne conoscere l'id. |
Metadati a costo graduato | Struttura, dimensioni e codici di un dataflow, chiedendo solo quello che serve invece di scaricare tutto. |
Estrazione dati | Risposta inline per query piccole, download su file per quelle grandi, con diagnosi leggibile quando la chiave è sbagliata. |
Risoluzione territoriale offline | 8.039 codici |
Cache a due livelli | In memoria (L1) + su disco (L2). Le codeliste sono condivise fra dataflow e valide 90 giorni. |
Rate limiting adattivo | Due finestre scorrevoli separate per endpoint leggeri e pesanti, che si restringono da sole quando ISTAT protesta. |
Installazione
Serve Python ≥ 3.11. Con uv:
git clone https://github.com/ManoloZocco/istat-mcp-suite.git
cd istat-mcp-suite
uv syncVerifica che parta:
uv run python -m istat_mcp.cli --transport stdioIl processo resta in attesa sullo stdin: è il comportamento corretto per un server
MCP in modalità stdio. Interrompi con Ctrl+C.
Modalità di trasporto
# STDIO — per Claude Desktop, Claude Code, Cursor e client locali in genere
uv run python -m istat_mcp.cli --transport stdio
# SSE / HTTP — per deploy remoti o client che parlano HTTP
uv run python -m istat_mcp.cli --transport sse --host 0.0.0.0 --port 8000Collegare un client MCP
Esempio per Claude Desktop (claude_desktop_config.json) o qualunque client che
usi lo stesso formato:
{
"mcpServers": {
"istat": {
"command": "uv",
"args": [
"--directory", "/percorso/assoluto/a/istat-mcp-suite",
"run", "python", "-m", "istat_mcp.cli", "--transport", "stdio"
]
}
}
}Con Claude Code:
claude mcp add istat -- uv --directory /percorso/assoluto/a/istat-mcp-suite \
run python -m istat_mcp.cli --transport stdioI tool disponibili
discover_dataflows(query, limit)
Cerca per parole chiave nel catalogo dei dataflow. Restituisce id, nome italiano e id della datastructure. È il punto di partenza quando non si conosce già l'id.
Il catalogo completo viene scaricato una volta (~2 MB, ~35 s) e messo in cache per 30 giorni; le ricerche successive sono locali.
get_constraints(dataflow_id, dimensions_only, dimension, max_codes_per_dimension, wait_seconds)
Metadati di un dataflow: dimensioni con la loro posizione SDMX, la codelist che sta dietro a ciascuna, e i codici validi con le etichette italiane.
Ha tre modalità, in ordine di costo crescente:
Chiamata | Cosa ottieni | Costo |
| Ordine e posizione delle dimensioni, template della chiave | 1 richiesta, pochi secondi su qualunque dataflow |
| I codici di una sola dimensione | 1–2 richieste |
default | Tutte le dimensioni con i codici | Può richiedere minuti, o restituire un risultato parziale |
Il troncamento è sempre dichiarato nella risposta (truncated, total_codes,
truncation_note) e tiene per primi i codici più aggregati: le sezioni NACE e i
totali prima delle sottoclassi, le regioni prima dei comuni.
Se l'endpoint availableconstraint di ISTAT non risponde entro wait_seconds, la
chiamata non si blocca: torna con status: "downloading" o "partial", la
struttura resta valida, e il download prosegue in background finendo in cache per
la chiamata successiva.
get_data(dataflow_id, key_filter, start_period, end_period, format, last_n_observations, max_inline_rows, force_file_download)
Estrae i dati veri e propri.
key_filter è una chiave SDMX puntata, non un dizionario: un segmento per
dimensione, nell'ordine di posizione dato da get_constraints.
A.053011.W_SUPPL+W_TOTLOS # frequenza annuale, comune di Grosseto, due misure
..W_SUPPL+W_TOTLOS # le stesse due misure, tutti i comuni, ogni frequenzaSegmento vuoto = tutti i valori di quella dimensione.
Più valori sullo stesso segmento si separano con
+.TIME_PERIODnon fa parte della chiave: si filtra constart_period/end_period.
Sotto le 500 righe la risposta è inline; oltre — o sopra 1 MB, o con
force_file_download=True — il dataset viene scritto su disco in
~/.cache/istat_mcp/downloads e la risposta contiene percorso, dimensione e
anteprima.
Quando ISTAT rifiuta la chiave (422/400/404), la risposta include l'arità attesa, il template corretto, il messaggio SDMX originale e un suggerimento su cosa correggere, invece del solo errore HTTP.
get_territorial_codes(search, level, limit)
Risoluzione offline su 8.039 entità REF_AREA: 1 nazione, 5 ripartizioni,
22 regioni e province autonome, 107 province, 7.904 comuni. Ricerca
case-insensitive su nome, codice REF_AREA e codice ISTAT.
search='Grosseto', level='comune' -> 053011
search='Grosseto', level='provincia' -> 053Da preferire sempre a get_constraints per la dimensione territoriale: è istantaneo,
non consuma slot del rate limiter e non rischia il blocco IP. Il dataset si rigenera
con python scripts/build_territorial_codes.py.
get_concepts(concept_id)
Definizione semantica di un concetto SDMX (REF_AREA, FREQ, …).
get_structure_diagram(dataflow_id)
Diagramma Mermaid della struttura dimensionale di un dataflow. Usa internamente
dimensions_only, quindi è veloce e immune allo stallo di availableconstraint.
get_cache_diagnostics()
Stato della cache, occupazione su disco, elenco dei file scaricati.
Come lo usa un agente
Il percorso che funziona, dal nome di un fenomeno alla tabella di dati:
flowchart TD
A["Serve un dato ISTAT"] --> B["discover_dataflows('verde urbano')"]
B --> C["get_constraints(id, dimensions_only=True)"]
C --> D{"Serve un territorio?"}
D -->|sì| E["get_territorial_codes('Grosseto', level='comune')"]
D -->|no| F["get_constraints(id, dimension='DATA_TYPE')"]
E --> F
F --> G["get_data(id, key_filter='A.053011.W_SUPPL')"]
G --> H{"Risposta grande?"}
H -->|inline| I["Dati nel contesto"]
H -->|file| J["Percorso su disco, da leggere con gli strumenti locali"]Le regole che fanno la differenza fra una sessione che funziona e una che brucia token e finestre di rate limit:
Partire sempre da
dimensions_only=True. Dà l'ordine delle dimensioni e il template della chiave — cioè tutto quello che serve per costruirekey_filter— in una sola richiesta. Enumerare i codici di tutte le dimensioni prima di sapere quali servono è lo spreco più comune.Per i territori usare
get_territorial_codes, maiget_constraints.CL_ITTER107ha 12.471 codici: chiederli a ISTAT quando la risposta è già su disco è tempo e rischio buttati.Chiedere una dimensione alla volta con
dimension='<ID>'invece della risoluzione completa.Sui dataflow con serie storiche lunghe passare
last_n_observations. Senza vincolo temporale ISTAT scandisce l'intera serie e la richiesta va in timeout; conlast_n_observations=1la stessa estrazione risponde in pochi secondi.Usare
force_file_downloadper i dataset grandi, invece di far passare megabyte di TSV dalla finestra di contesto.Leggere
statusnella risposta."downloading"e"partial"non sono errori: sono risposte valide su cui si può già lavorare, e la chiamata successiva troverà il resto in cache.
Limiti dell'API ISTAT
Comportamenti verificati contro esploradati.istat.it. Non sono bug di questo
server: sono il terreno su cui lavora, ed è utile conoscerli anche solo per
interpretare le risposte.
availableconstraint è l'endpoint che si pianta. Su
183_1163_DF_DICA_ASIAULP_TERRIFDATA_7 non ha risposto dopo 600 s, mentre sullo
stesso dataflow la struttura arriva in ~4 s e l'intera DSD con tutte le codeliste
(11 MB) in ~9 s. Su altri dataflow lo stesso endpoint risponde in 34 s, o fra 4 e
46 s a seconda del momento. Per questo viene scaricato in background e la risposta
torna comunque.
Le codeliste sono enormi ma veloci. CL_ITTER107 sono 12.471 codici (9,1 MB
in ~4 s), CL_ATECO_2007 2.063. Il problema che creano non è il tempo ma il limite
di token della risposta: di qui il troncamento dichiarato.
Un id di dataflow non è un id di datastructure. 609_1_DF_DCCV_URBANENV_1 è
servito dalla DSD DCCV_URBANENV, 22_389 da DCIS_POPRES1. Interrogare
datastructure/IT1/<dataflow_id> restituisce sempre 404.
ISTAT serve SDMX-CSV anche quando si chiede TSV. La risposta riporta il formato
reale in format e quello richiesto in requested_format; il file salvato prende
l'estensione reale.
Sugli endpoint di struttura serve un Accept XML esplicito, altrimenti ISTAT
restituisce SDMX-JSON che i parser XML non digeriscono.
Un codice presente nella codelist può non essere pubblicato dal dataflow.
CL_TIPO_DATO_CIS ha 260 tipi di dato, ma un dato dataflow può esporne due. In quel
caso ISTAT risponde 404 NoRecordsFound, che significa "nessuna osservazione", non
"codice inesistente".
Il catalogo dei dataflow va chiesto con detail=allstubs: ~2 MB / ~35 s invece
di ~13 MB / ~70 s.
Blocco dell'indirizzo IP
⚠️ Il limite più importante da conoscere.
ISTAT non pubblica alcun limite di frequenza: le risposte non contengono header
X-RateLimit-* né Retry-After, e raffiche brevi passano senza throttling. Non
esiste quindi una soglia documentata a cui attenersi.
Esiste però un blocco a livello di indirizzo IP: dopo un uso intenso e
prolungato — molte estrazioni dati pesanti, sessioni lunghe, download ripetuti —
esploradati.istat.it smette di rispondere da quell'IP. Non arriva un 429 con una
spiegazione: le richieste iniziano semplicemente a fallire o a non tornare più,
anche dopo aver rallentato.
Come si riconosce: tutte le richieste falliscono o vanno in timeout, comprese quelle leggere che prima rispondevano in pochi secondi, e il sito ISTAT è irraggiungibile anche dal browser sulla stessa rete.
Come si risolve: cambiando indirizzo IP pubblico.
Su una linea domestica con IP dinamico: riavviare il modem/router e attendere che il provider ne assegni uno nuovo (a volte servono alcuni minuti di modem spento perché il vecchio lease scada).
In alternativa: passare a un'altra rete (hotspot del telefono), o usare una VPN che esca da un IP diverso.
Se l'IP è statico, non c'è modo di sbloccarlo se non aspettare.
Come si evita. Il server è costruito per ridurre il rischio, ma non può azzerarlo:
La cache su disco (30 giorni per la struttura, 90 per le codeliste) fa sì che il lavoro ripetuto non arrivi mai a ISTAT.
Il rate limiter separa gli endpoint per costo: struttura a 20/min, dati e
availableconstrainta 3/min, ed entrambe le finestre si dimezzano su un 429 o 503 e risalgono di uno slot ogni due minuti.La risoluzione territoriale è completamente offline.
Il resto dipende dall'uso: preferire dimensions_only e dimension=, non
riscaricare dataset già presenti in ~/.cache/istat_mcp/downloads, ed evitare di
lanciare estrazioni sull'intero catalogo. La cache va tenuta, non svuotata:
cancellarla significa rifare da capo tutte le richieste che aveva assorbito.
Configurazione
Tutte le impostazioni si sovrascrivono con variabili d'ambiente o con un file
.env nella directory di lavoro.
Variabile | Default | Note |
|
| Endpoint SDMX |
|
| Timeout richieste normali |
|
| Timeout lettura per i download in streaming |
|
| Slot/minuto per |
|
| Slot/minuto per gli endpoint di struttura |
|
| Ampiezza della finestra scorrevole |
|
| Intervallo di recupero di uno slot dopo un 429/503 |
|
| Cache L2 su disco |
|
| Dataset scaricati |
|
| Soglia oltre la quale si passa al file |
|
| TTL metadati |
|
| TTL dati |
MCP_STORAGE_DIR sta sotto $HOME e non nella directory del progetto di
proposito: un percorso relativo al repo non è raggiungibile da una shell in
sandbox, e i file risulterebbero elencati dal tool ma non leggibili.
Sviluppo
uv run pytest # suite completa
uv run pytest -q # output compattoStruttura del sorgente:
src/istat_mcp/
├── cli.py # entry point, scelta del trasporto
├── config.py # impostazioni (pydantic-settings)
├── server.py # registrazione dei tool su FastMCP
├── core/
│ ├── cache.py # cache L1 in memoria + L2 su disco
│ ├── client.py # client SDMX, rate limiting, retry, streaming
│ └── storage.py # scrittura dei dataset su disco
├── data/
│ ├── territorial_codes.json
│ └── territory.py # risolutore territoriale offline
└── tools/
├── data.py # get_data, diagnostica cache
├── discovery.py # discover_dataflows
└── metadata.py # get_constraints, concetti, diagrammi, territoriDue vincoli da rispettare toccando il codice:
Le funzioni dei tool non accettano il client SDMX come parametro. FastMCP costruisce il modello degli argomenti con pydantic a partire dalle annotazioni: una classe arbitraria come
IstatSDMXClientnella firma fa fallire ogni chiamata conPydanticSchemaGenerationError, prima ancora della richiesta HTTP. Tutti i tool usano il singletonistat_mcp.core.client.global_client.I tool restituiscono oggetti JSON strutturati, non stringhe JSON annidate, così il client fa un solo parse.
Licenza
MIT.
I dati restano dell'Istituto Nazionale di Statistica e sono soggetti alle condizioni d'uso pubblicate su istat.it. Questo è un progetto indipendente, non affiliato con l'ISTAT.
Available Tools
7 toolsdiscover_dataflowsA
Search ~4,700 available ISTAT statistical datasets (dataflows) by keywords. Returns dataflow id, Italian name and the datastructure id to feed into get_constraints.
Inputs: query (required), limit. Returns: object
get_cache_diagnosticsA
Inspect cache hit/miss diagnostics, disk usage, and downloaded files list.
Inputs: no named parameters. Returns: object
get_conceptsA
Get semantic definitions for ISTAT SDMX concept IDs (e.g. REF_AREA, FREQ).
Inputs: concept_id. Returns: object
get_constraintsA
Single-Call Metadata Tool: retrieves dimensions (with their position), valid constrained code values, and human-readable Italian/English labels for an ISTAT dataset in 1 query. Replaces the separate get_structure and get_codelist_description tools of earlier versions. Call this before get_data to build the key_filter.
Inputs: dataflow_id (required). Returns: object
get_dataA
Fetch statistical data from ISTAT. Returns formatted text inline for small queries and automatically downloads to a local disk file for large datasets, for payloads above 1 MB, or when force_file_download=True. The key_filter is a dotted SDMX key string (e.g. 'A.053011.W_SUPPL+W_TOTLOS'), not a dictionary. On dataflows with long time series (e.g. 22_389) pass last_n_observations=1, otherwise ISTAT scans the whole series and the request times out.
Inputs: dataflow_id (required), format, end_period, key_filter, +4 more. Returns: object
get_structure_diagramA
Generate a Mermaid.js diagram showing dataset dimensions, codelists, and hierarchies.
Inputs: dataflow_id (required). Returns: result
get_territorial_codesA
Instant offline lookup across 8,039 official ISTAT REF_AREA territorial codes (Comuni, Province, Regioni, Ripartizioni). Case-insensitive on name, REF_AREA code and ISTAT code. Example: search='Grosseto', level='comune' -> 053011.
Inputs: search (required), level, limit. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct role: dataflow discovery, dataset constraints, concept definitions, structure diagrams, territorial code lookup, data retrieval, and cache diagnostics. Even the metadata-related tools (constraints, concepts, diagram, codes) are clearly separated by their specific inputs and outputs, so an agent should rarely confuse them.
Most tools follow a consistent get_<noun> pattern (get_constraints, get_concepts, get_data, etc.), with one notable deviation: discover_dataflows. This is still acceptable since 'discover' conveys a search action, but it breaks the uniform get_ prefix. Overall the naming is predictable and readable.
7 tools is well within the ideal range for a domain-specific server. Each tool serves a clear purpose in the workflow (discover → constrain → fetch → diagnose), and none are redundant or unnecessary. The count feels intentionally scoped.
The core workflow of discovering datasets, retrieving their constraints, and fetching data is fully covered. Supporting tools for semantic concepts, territorial codes, structure visualization, and cache diagnostics fill out the domain nicely. Minor gaps include an inability to list all dataflows without a keyword and no explicit way to get raw dataflow metadata beyond constraints, but these are workarounds rather than dead ends.
Maintenance
Related MCP Connectors
ISTAT (Istituto Nazionale di Statistica) MCP — Italy's national statistics via the public SDMX 2.1…
Search and query 1,500+ OECD statistical datasets via SDMX. Keyless.
Unofficial Eurostat MCP — wraps Eurostat Statistical Data API (no auth required)
Query official statistics of Catalonia (Idescat): tables, metadata and JSON-stat data via MCP.
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides access to Catalonia's statistical data via the IDESCAT Tables API v2. It enables users to navigate catalogs, inspect metadata, and query data with territorial filters and resolved labels.51-
- AlicenseNot gradedqualityBmaintenanceEnables querying Italian national statistics (ISTAT) data through natural language questions, with tools for accessing demographic, economic, and social indicators.85 npmMIT
- AlicenseAqualityDmaintenanceEnables LLMs to access and analyze Italian statistical data from ISTAT via natural language queries, supporting dataset discovery, exploration, and data retrieval.927 PyPI2MIT
- AlicenseAqualityDmaintenanceEnables natural language discovery, querying, and analysis of Thailand's official statistics from the National Statistical Office via SDMX REST API. It provides tools for searching dataflows, exploring structures, and fetching data with caching and bilingual support.8MIT