Skip to main content
Glama
istat-mcp-server

istat-mcp-server

by Halpph

ISTAT MCP Server

PyPI Tests License: MIT Python 3.10+

A Model Context Protocol (MCP) server that enables Large Language Models to access and analyze data from the Italian National Statistical Institute (ISTAT) directly.

What is this?

This MCP server allows LLMs like Claude to seamlessly query, filter, and download statistical datasets from ISTAT, enabling natural language data analysis workflows. Instead of manually searching for datasets, constructing API queries, and downloading data, you can simply ask your LLM to find and analyze Italian statistical data.

Built on top of: This server uses the excellent istatapi open-source Python wrapper by ondata, which simplifies interaction with ISTAT's SDMX REST API.

Related MCP server: eurostat-mcp

Features

  • Dataset Discovery: Search and browse all available ISTAT datasets

  • Dimension Exploration: Inspect dataset structure and available filters

  • Flexible Data Retrieval: Get data directly in JSON or download large datasets

  • Smart Error Handling: Automatic fallback to file downloads for large/timeout scenarios

  • Secure Storage: Configurable storage directory with path traversal protection

  • Cross-Platform: Works on WSL, Windows, macOS, and Linux

Use Cases

Enable your LLM to:

  • Find Italian economic indicators (GDP, unemployment, inflation)

  • Analyze demographic trends and population statistics

  • Compare regional data across Italy

  • Download and process large statistical datasets

  • Create data visualizations from ISTAT data

  • Answer questions about Italian statistics naturally

Installation

The easiest way to use this MCP server is directly with uvx - no installation required:

uvx istat-mcp-server

Install from PyPI

# Using pip
pip install istat-mcp-server

# Using uv
uv pip install istat-mcp-server

Install from Source (for development)

# Clone the repository
git clone https://github.com/Halpph/istat-mcp-server.git
cd istat-mcp-server

# Install with uv (recommended)
uv sync

# Or install with pip
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Configuration

Claude Desktop Setup

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "istat": {
      "command": "uvx",
      "args": ["istat-mcp-server"],
      "env": {
        "MCP_STORAGE_DIR": "/path/to/data/storage"
      }
    }
  }
}

That's it! Claude Desktop will automatically download and run the server from PyPI.

Alternative: Running from local installation

If you installed from source or want to run a development version:

{
  "mcpServers": {
    "istat": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/istat-mcp-server",
        "run",
        "istat-mcp-server"
      ],
      "env": {
        "MCP_STORAGE_DIR": "/path/to/data/storage"
      }
    }
  }
}

Storage Configuration

By default, downloaded files are saved to:

  • WSL: /mnt/c/Users/Public/Downloads/mcp-data/

  • Windows: %USERPROFILE%\Downloads\mcp-data

  • Linux/macOS: ./data

Override this by setting the MCP_STORAGE_DIR environment variable.

Other Environment Variables

  • MCP_DEBUG: Set to true for detailed error tracebacks in responses

Available Tools

Dataset Discovery

  • get_list_of_available_datasets() - List all available ISTAT datasets

  • search_datasets(query) - Search datasets by keyword

Dataset Exploration

  • get_dataset_dimensions(dataflow_identifier) - Get dimensions/structure of a dataset

  • get_dimension_values(dataflow_identifier, dimension) - Get possible values for a dimension

Data Retrieval

  • get_data(dataflow_identifier, filters) - Get data with filters (or URL if too large)

  • get_data_limited(dataflow_identifier, filters, limit) - Get limited number of records

  • get_summary(dataflow_identifier, filters) - Get statistical summary of filtered data

File Operations

  • get_dataset_url(dataflow_identifier, filters) - Get download URL with metadata

  • download_dataset(url, output_path) - Download dataset to local storage

Example Usage

With Claude Desktop

Once configured, you can interact naturally:

You: "Find datasets about Italian unemployment"

Claude: [Uses search_datasets tool]
I found several unemployment datasets...

You: "Get the monthly unemployment rate for 2024"

Claude: [Uses get_dataset_dimensions, get_dimension_values, get_data tools]
Here's the unemployment data for 2024...

Programmatic Usage

from mcp.client import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to the server
server_params = StdioServerParameters(
    command="uvx",
    args=["istat-mcp-server"]
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # List available tools
        tools = await session.list_tools()

        # Call a tool
        result = await session.call_tool("search_datasets", {"query": "unemployment"})

Development

Running Tests

# With uv
uv run pytest

# With pip
pytest

Project Structure

istat-mcp-server/
├── main.py              # Main MCP server implementation
├── test_main.py         # Comprehensive test suite
├── pyproject.toml       # Project metadata and dependencies
├── uv.lock             # Dependency lock file
├── README.md           # This file
├── CONTRIBUTING.md     # Contribution guidelines
├── LICENSE             # MIT License
├── docs/               # Additional documentation
│   ├── TESTING.md     # Testing guide
│   └── ISTATAPI_REFERENCE.md  # API reference
├── examples/           # Example configurations
│   └── gemini-extension.json  # Gemini setup example
└── .github/
    └── workflows/      # CI/CD pipelines
        ├── test.yml   # Automated testing
        └── release.yml # Release automation

How It Works

  1. MCP Protocol: The server implements the Model Context Protocol, exposing ISTAT data operations as "tools" that LLMs can call

  2. ISTAT API Wrapper: Uses the istatapi library to interact with ISTAT's SDMX REST API

  3. Smart Handling: Automatically handles large datasets by falling back to file downloads

  4. Secure Storage: All file operations are restricted to a configured storage directory

Credits

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! We appreciate bug reports, feature requests, documentation improvements, and code contributions.

Please see CONTRIBUTING.md for detailed guidelines on:

  • Setting up your development environment

  • Running tests

  • Code style and conventions

  • Submitting pull requests

Quick start for contributors:

# Fork and clone the repo
git clone https://github.com/YOUR_USERNAME/istat-mcp-server.git
cd istat-mcp-server

# Install dependencies
uv sync

# Run tests
uv run pytest

# Make your changes and submit a PR!

Roadmap

Future enhancements planned:

  • Add caching for frequently accessed datasets

  • Support for more data export formats (CSV, JSON, Excel)

  • Integration with data visualization tools

  • Support for ISTAT time series analysis

  • Multi-language support (Italian/English metadata)

FAQ

How do I find the right dataset?

Use the search_datasets tool with keywords like "unemployment", "GDP", "population", etc. The tool searches through all ISTAT dataset titles and descriptions.

Why am I getting a URL instead of data?

For large datasets or when the API times out, the server automatically returns a download URL instead. You can then use the download_dataset tool to save the data locally.

Can I use this with other LLMs besides Claude?

Yes! Any MCP-compatible client can use this server. See the MCP documentation for more information.

Where is the downloaded data stored?

By default:

  • WSL: /mnt/c/Users/Public/Downloads/mcp-data/

  • Windows: %USERPROFILE%\Downloads\mcp-data

  • Linux/macOS: ./data

You can customize this with the MCP_STORAGE_DIR environment variable.

Changelog

Version 0.1.2 (2024-10-14)

  • Fixed: Automatic file format detection in download_dataset function

    • Files now saved with correct extension based on HTTP Content-Type header

    • XML/SDMX files from ISTAT API no longer saved as .csv

    • Added support for XML, CSV, JSON, TXT, and unknown formats

    • Response now includes detected_extension and file_format fields

  • Tests: Added comprehensive test coverage for format detection scenarios

Version 0.1.1 (2024-10-14)

  • Fixed path resolution for cross-platform compatibility (macOS, Windows, Linux, WSL)

  • Updated documentation

See Releases for complete version history.

Support

For issues or questions:

Acknowledgments

  • ondata for the excellent istatapi Python wrapper

  • ISTAT for providing comprehensive statistical data about Italy

  • Anthropic for developing the Model Context Protocol

Available Tools

9 tools
download_datasetA
Download a dataset file from a URL to a local path with automatic format detection.
Better for large datasets that cannot be handled in-memory or when Json responses are too large or not supported.
The file extension is automatically determined from the Content-Type header.

Args:
    url: The URL of the file to download.
    output_path: Optional. A relative or absolute path for the saved file.
                 If relative, it's resolved against the configured storage directory.
                 If absolute, it MUST be inside the storage directory.
                 If not provided, a filename is generated from the URL with the appropriate extension.

Example:
    # Saves to <storage_dir>/my_data/export.xml (extension based on content type)
    download_dataset(url="http://.../data", output_path="my_data/export")

    # Saves to <storage_dir>/<generated_name>.<ext> (extension based on content type)
    download_dataset(url="http://.../data")

Inputs: url (required), output_path. Returns: result

get_dataA
Get data from a dataset with filters. Attempt to retrieve data, if it times out or is too big,
return the URL of the file to download.

Args:
    dataflow_identifier: The identifier of the dataset.
    filters: A dictionary of filters to apply to the dataset.

Example:
    get_data(dataflow_identifier="139_176", filters={"freq": "M", "tipo_dato": ["ISAV", "ESAV"], "paese_partner": "WORLD"})

Inputs: dataflow_identifier (required), filters (required). Returns: result

get_data_limitedA
Get limited data from a dataset with filters. Returns only the first N records.
Attempt to retrieve data, if it times out or is too big, return the URL of the file to download.

Args:
    dataflow_identifier: The identifier of the dataset.
    filters: A dictionary of filters to apply to the dataset.
    limit: The maximum number of records to return.

Example:
    get_data_limited(dataflow_identifier="139_176", filters={"freq": "M", "tipo_dato": ["ISAV", "ESAV"], "paese_partner": "WORLD"}, limit=100)

Inputs: dataflow_identifier (required), filters (required), limit (required). Returns: result

get_dataset_dimensionsC

Get the dimensions of a dataset

Args:
    dataflow_identifier: The identifier of the dataset.

Example:
    get_dataset_dimensions(dataflow_identifier="139_176")

Inputs: dataflow_identifier (required). Returns: result

get_dataset_urlA
Get the URL to download a dataset with metadata.

Args:
    dataflow_identifier: The identifier of the dataset.
    filters: A dictionary of filters to apply to the dataset.
        Filter keys should be dimension names in lowercase.
        For unfiltered dimensions, omit them or set to None.

Example:
    get_dataset_url(dataflow_identifier="139_176", filters={"freq": "M", "tipo_dato": ["ISAV", "ESAV"], "paese_partner": "WORLD"})

Returns:
    JSON with URL and metadata (content-type, size, etc.)

Inputs: dataflow_identifier (required), filters (required). Returns: result

get_dimension_valuesC

Get the values of a dimension for a given dataset

Args:
    dataflow_identifier: The identifier of the dataset.
    dimension: The dimension to get the values for.

Example:
    get_dimension_values(dataflow_identifier="139_176", dimension="TIPO_DATO")

Inputs: dataflow_identifier (required), dimension (required). Returns: result

get_list_of_available_datasetsA

Get a list of available datasets from ISTAT

Example:
    get_list_of_available_datasets()

Inputs: no named parameters. Returns: result

get_summaryA
Get a summary of a dataset from ISTAT.

Args:
    dataflow_identifier: The identifier of the dataset.
    filters: A dictionary of filters to apply to the dataset.
    
Example:
    get_summary(dataflow_identifier="139_176", filters={"freq": "M", "tipo_dato": ["ISAV", "ESAV"], "paese_partner": "WORLD"})

Inputs: dataflow_identifier (required), filters (required). Returns: result

search_datasetsA

Search datasets in ISTAT website by a query string

Args:
    query: The query string to search for.
    
Example:
    search_datasets(query="import")

Inputs: query (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    Tools are mostly distinct: download_dataset handles file download, get_data and get_data_limited differ by limit, and others cover distinct metadata and discovery functions. Slight overlap between get_data and get_data_limited could cause confusion but descriptions clarify.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case (get_, download_, search_), making them predictable and easy to use.

    Tool Count5/5

    With 9 tools covering discovery, metadata, and data retrieval, the count is well-scoped for an ISTAT data access server—neither too many nor too few.

    Completeness5/5

    The tool set provides a complete workflow: dataset discovery (list, search), metadata exploration (dimensions, summary), and data retrieval with multiple options (filtered, limited, URL, download). No obvious gaps for its intended purpose.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables querying Italian national statistics (ISTAT) data through natural language questions, with tools for accessing demographic, economic, and social indicators.
      145 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Exposes the Eurostat Statistics API, enabling LLMs to discover, explore, and retrieve official EU statistical data through search, dimension inspection, and data retrieval tools.
      3
      -