A Model Context Protocol (MCP) server that enables Large Language Models to access and analyze data from the Italian National Statistical Institute (ISTAT) directly.
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.
- 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
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
The easiest way to use this MCP server is directly with uvx - no installation required:
uvx istat-mcp-server# Using pip
pip install istat-mcp-server
# Using uv
uv pip install istat-mcp-server# 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 .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.
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"
}
}
}
}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.
MCP_DEBUG: Set totruefor detailed error tracebacks in responses
get_list_of_available_datasets()- List all available ISTAT datasetssearch_datasets(query)- Search datasets by keyword
get_dataset_dimensions(dataflow_identifier)- Get dimensions/structure of a datasetget_dimension_values(dataflow_identifier, dimension)- Get possible values for a dimension
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 recordsget_summary(dataflow_identifier, filters)- Get statistical summary of filtered data
get_dataset_url(dataflow_identifier, filters)- Get download URL with metadatadownload_dataset(url, output_path)- Download dataset to local storage
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...
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"})# With uv
uv run pytest
# With pip
pytestistat-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
- MCP Protocol: The server implements the Model Context Protocol, exposing ISTAT data operations as "tools" that LLMs can call
- ISTAT API Wrapper: Uses the istatapi library to interact with ISTAT's SDMX REST API
- Smart Handling: Automatically handles large datasets by falling back to file downloads
- Secure Storage: All file operations are restricted to a configured storage directory
- ISTAT API Wrapper: This project relies on istatapi by ondata, an excellent open-source Python wrapper for ISTAT's SDMX API
- Data Source: ISTAT (Istituto Nazionale di Statistica) - Italian National Institute of Statistics
- MCP Protocol: Anthropic's Model Context Protocol
MIT License - see LICENSE file for details
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!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)
Use the search_datasets tool with keywords like "unemployment", "GDP", "population", etc. The tool searches through all ISTAT dataset titles and descriptions.
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.
Yes! Any MCP-compatible client can use this server. See the MCP documentation for more information.
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.
- Fixed: Automatic file format detection in
download_datasetfunction- 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_extensionandfile_formatfields
- Tests: Added comprehensive test coverage for format detection scenarios
- Fixed path resolution for cross-platform compatibility (macOS, Windows, Linux, WSL)
- Updated documentation
See Releases for complete version history.
For issues or questions:
- Open an issue on GitHub
- Check ISTAT API documentation
- Refer to istatapi guide