ISTAT MCP Server

English | Italiano

MCP server for accessing Italian statistical data from the ISTAT SDMX API.

Overview

This Model Context Protocol (MCP) server provides Claude Desktop with access to Italian statistical data from ISTAT (Istituto Nazionale di Statistica) through the SDMX REST API. It implements a two-layer caching mechanism to minimize API calls and provides eight tools for discovering, querying, and retrieving statistical data.

Features

• 8 MCP Tools for data discovery and retrieval:

  • discover_dataflows - Find available datasets by keywords (with blacklist filtering)
  • get_structure - Get dimension definitions and codelists for a datastructure ID
  • get_constraints - Get available constraint values for each dimension with descriptions (combines structure + constraints + codelist descriptions)
  • get_codelist_description - Get descriptions in Italian/English for codelist values
  • get_concepts - Get semantic definitions of SDMX concepts
  • get_data - Fetch actual statistical data in TSV table format (with blacklist validation)
  • get_cache_diagnostics - Debug tool to inspect cache status
  • get_territorial_codes - Resolve ISTAT REF_AREA codes for Italia, ripartizioni, regioni, province, and comuni

• Recommended Workflow (simple and efficient):

  1. Discover: Use discover_dataflows to find the dataflow you're interested in
  2. Get Complete Metadata: Use get_constraints to see all dimensions with valid values AND descriptions in one call
     • This is the RECOMMENDED approach - one call instead of many
     • Internally combines get_structure + get_codelist_description for all dimensions
     • All data cached for 1 month → subsequent calls are instant
     • Returns complete information ready for building filters in get_data
  3. Fetch Data: Use get_data with the appropriate dimension filters to retrieve actual data

  Alternative workflow (manual approach):

  • Use get_structure with a datastructure ID to see dimensions and their codelists
  • Then call get_codelist_description manually for each codelist you need
  • Use get_concepts if you need semantic definitions of dimensions/attributes

• Two-Layer Cache:

  • In-memory cache (cachetools) for fast access during session
  • Persistent disk cache (diskcache) that survives restarts

• Rate Limiting: Maximum 3 API calls per minute with automatic queuing

• Retry Logic: Exponential backoff on transient errors

• Dataflow Blacklist: Filter out specific dataflows from all queries

Installation

1. Clone the repository:

git clone https://github.com/ondata/istat_mcp_server.git
cd istat_mcp_server

2. Create a virtual environment and install dependencies (Python >=3.11 required):

With uv (recommended):

uv sync

uv sync automatically creates a .venv directory and installs all dependencies into it. To run commands manually, activate it first:

# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate

With pip:

python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate
pip install -e .

3. Create a .env file (optional, uses defaults if not present):

cp .env.example .env

Optional: for slow availableconstraint responses used by get_constraints, set:

AVAILABLECONSTRAINT_TIMEOUT_SECONDS=180

MCP Client Configuration

This server works with any MCP-compatible client. The sections below cover the most common ones.

Claude Desktop | Claude Code | Gemini CLI | VS Code | Codex CLI | Claude Desktop on Windows with Python on WSL2

In all examples, replace /path/to/istat_mcp_server with the actual path to this directory, and python with python3 if needed on your system.

... View full README on GitHub