| Name | istat-mcp-server JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Model Context Protocol server for accessing Italian National Statistical Institute (ISTAT) data |
| upload_time | 2025-10-14 12:43:49 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
claude
data
istat
italy
llm
mcp
sdmx
statistics
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ISTAT MCP Server
[](https://pypi.org/project/istat-mcp-server/)
[](https://github.com/Halpph/istat-mcp-server/actions/workflows/test.yml)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://github.com/ondata/guida-api-istat) open-source Python wrapper by ondata, which simplifies interaction with ISTAT's SDMX REST API.
## 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
### Quick Start (Recommended)
The easiest way to use this MCP server is directly with `uvx` - no installation required:
```bash
uvx istat-mcp-server
```
### Install from PyPI
```bash
# Using pip
pip install istat-mcp-server
# Using uv
uv pip install istat-mcp-server
```
### Install from Source (for development)
```bash
# 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`
```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:
```json
{
"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
```python
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
```bash
# 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](https://github.com/ondata/guida-api-istat) 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
- **ISTAT API Wrapper**: This project relies on [istatapi](https://github.com/ondata/guida-api-istat) by [ondata](https://github.com/ondata), an excellent open-source Python wrapper for ISTAT's SDMX API
- **Data Source**: [ISTAT (Istituto Nazionale di Statistica)](https://www.istat.it/) - Italian National Institute of Statistics
- **MCP Protocol**: [Anthropic's Model Context Protocol](https://modelcontextprotocol.io/)
## License
MIT License - see [LICENSE](LICENSE) file for details
## Contributing
Contributions are welcome! We appreciate bug reports, feature requests, documentation improvements, and code contributions.
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:
- Setting up your development environment
- Running tests
- Code style and conventions
- Submitting pull requests
Quick start for contributors:
```bash
# 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](https://modelcontextprotocol.io/) 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
See [Releases](https://github.com/Halpph/istat-mcp-server/releases) for version history and changes.
## Support
For issues or questions:
- Open an issue on [GitHub](https://github.com/Halpph/istat-mcp-server/issues)
- Check [ISTAT API documentation](https://www.istat.it/en/web-services)
- Refer to [istatapi guide](https://github.com/ondata/guida-api-istat)
## Acknowledgments
- **[ondata](https://github.com/ondata)** for the excellent [istatapi](https://github.com/ondata/guida-api-istat) Python wrapper
- **[ISTAT](https://www.istat.it/)** for providing comprehensive statistical data about Italy
- **[Anthropic](https://www.anthropic.com/)** for developing the Model Context Protocol
Raw data
{
"_id": null,
"home_page": null,
"name": "istat-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "claude, data, istat, italy, llm, mcp, sdmx, statistics",
"author": null,
"author_email": "Alessio Cesaretti <alessio.cesaretti@hotmail.it>",
"download_url": "https://files.pythonhosted.org/packages/1b/6e/3cdb2074c230530d732f5be2b63cfb254e775055650751d2b7f3784daf11/istat_mcp_server-0.1.1.tar.gz",
"platform": null,
"description": "# ISTAT MCP Server\n\n[](https://pypi.org/project/istat-mcp-server/)\n[](https://github.com/Halpph/istat-mcp-server/actions/workflows/test.yml)\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables Large Language Models to access and analyze data from the Italian National Statistical Institute (ISTAT) directly.\n\n## What is this?\n\nThis 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.\n\n**Built on top of:** This server uses the excellent [istatapi](https://github.com/ondata/guida-api-istat) open-source Python wrapper by ondata, which simplifies interaction with ISTAT's SDMX REST API.\n\n## Features\n\n- **Dataset Discovery**: Search and browse all available ISTAT datasets\n- **Dimension Exploration**: Inspect dataset structure and available filters\n- **Flexible Data Retrieval**: Get data directly in JSON or download large datasets\n- **Smart Error Handling**: Automatic fallback to file downloads for large/timeout scenarios\n- **Secure Storage**: Configurable storage directory with path traversal protection\n- **Cross-Platform**: Works on WSL, Windows, macOS, and Linux\n\n## Use Cases\n\nEnable your LLM to:\n- Find Italian economic indicators (GDP, unemployment, inflation)\n- Analyze demographic trends and population statistics\n- Compare regional data across Italy\n- Download and process large statistical datasets\n- Create data visualizations from ISTAT data\n- Answer questions about Italian statistics naturally\n\n## Installation\n\n### Quick Start (Recommended)\n\nThe easiest way to use this MCP server is directly with `uvx` - no installation required:\n\n```bash\nuvx istat-mcp-server\n```\n\n### Install from PyPI\n\n```bash\n# Using pip\npip install istat-mcp-server\n\n# Using uv\nuv pip install istat-mcp-server\n```\n\n### Install from Source (for development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/Halpph/istat-mcp-server.git\ncd istat-mcp-server\n\n# Install with uv (recommended)\nuv sync\n\n# Or install with pip\npython -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\npip install -e .\n```\n\n## Configuration\n\n### Claude Desktop Setup\n\nAdd this to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"istat\": {\n \"command\": \"uvx\",\n \"args\": [\"istat-mcp-server\"],\n \"env\": {\n \"MCP_STORAGE_DIR\": \"/path/to/data/storage\"\n }\n }\n }\n}\n```\n\nThat's it! Claude Desktop will automatically download and run the server from PyPI.\n\n#### Alternative: Running from local installation\n\nIf you installed from source or want to run a development version:\n\n```json\n{\n \"mcpServers\": {\n \"istat\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/absolute/path/to/istat-mcp-server\",\n \"run\",\n \"istat-mcp-server\"\n ],\n \"env\": {\n \"MCP_STORAGE_DIR\": \"/path/to/data/storage\"\n }\n }\n }\n}\n```\n\n### Storage Configuration\n\nBy default, downloaded files are saved to:\n- **WSL**: `/mnt/c/Users/Public/Downloads/mcp-data/`\n- **Windows**: `%USERPROFILE%\\Downloads\\mcp-data`\n- **Linux/macOS**: `./data`\n\nOverride this by setting the `MCP_STORAGE_DIR` environment variable.\n\n### Other Environment Variables\n\n- `MCP_DEBUG`: Set to `true` for detailed error tracebacks in responses\n\n## Available Tools\n\n### Dataset Discovery\n\n- `get_list_of_available_datasets()` - List all available ISTAT datasets\n- `search_datasets(query)` - Search datasets by keyword\n\n### Dataset Exploration\n\n- `get_dataset_dimensions(dataflow_identifier)` - Get dimensions/structure of a dataset\n- `get_dimension_values(dataflow_identifier, dimension)` - Get possible values for a dimension\n\n### Data Retrieval\n\n- `get_data(dataflow_identifier, filters)` - Get data with filters (or URL if too large)\n- `get_data_limited(dataflow_identifier, filters, limit)` - Get limited number of records\n- `get_summary(dataflow_identifier, filters)` - Get statistical summary of filtered data\n\n### File Operations\n\n- `get_dataset_url(dataflow_identifier, filters)` - Get download URL with metadata\n- `download_dataset(url, output_path)` - Download dataset to local storage\n\n## Example Usage\n\n### With Claude Desktop\n\nOnce configured, you can interact naturally:\n\n```\nYou: \"Find datasets about Italian unemployment\"\n\nClaude: [Uses search_datasets tool]\nI found several unemployment datasets...\n\nYou: \"Get the monthly unemployment rate for 2024\"\n\nClaude: [Uses get_dataset_dimensions, get_dimension_values, get_data tools]\nHere's the unemployment data for 2024...\n```\n\n### Programmatic Usage\n\n```python\nfrom mcp.client import ClientSession, StdioServerParameters\nfrom mcp.client.stdio import stdio_client\n\n# Connect to the server\nserver_params = StdioServerParameters(\n command=\"uvx\",\n args=[\"istat-mcp-server\"]\n)\n\nasync with stdio_client(server_params) as (read, write):\n async with ClientSession(read, write) as session:\n # List available tools\n tools = await session.list_tools()\n\n # Call a tool\n result = await session.call_tool(\"search_datasets\", {\"query\": \"unemployment\"})\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# With uv\nuv run pytest\n\n# With pip\npytest\n```\n\n### Project Structure\n\n```\nistat-mcp-server/\n\u251c\u2500\u2500 main.py # Main MCP server implementation\n\u251c\u2500\u2500 test_main.py # Comprehensive test suite\n\u251c\u2500\u2500 pyproject.toml # Project metadata and dependencies\n\u251c\u2500\u2500 uv.lock # Dependency lock file\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 CONTRIBUTING.md # Contribution guidelines\n\u251c\u2500\u2500 LICENSE # MIT License\n\u251c\u2500\u2500 docs/ # Additional documentation\n\u2502 \u251c\u2500\u2500 TESTING.md # Testing guide\n\u2502 \u2514\u2500\u2500 ISTATAPI_REFERENCE.md # API reference\n\u251c\u2500\u2500 examples/ # Example configurations\n\u2502 \u2514\u2500\u2500 gemini-extension.json # Gemini setup example\n\u2514\u2500\u2500 .github/\n \u2514\u2500\u2500 workflows/ # CI/CD pipelines\n \u251c\u2500\u2500 test.yml # Automated testing\n \u2514\u2500\u2500 release.yml # Release automation\n```\n\n## How It Works\n\n1. **MCP Protocol**: The server implements the Model Context Protocol, exposing ISTAT data operations as \"tools\" that LLMs can call\n2. **ISTAT API Wrapper**: Uses the [istatapi](https://github.com/ondata/guida-api-istat) library to interact with ISTAT's SDMX REST API\n3. **Smart Handling**: Automatically handles large datasets by falling back to file downloads\n4. **Secure Storage**: All file operations are restricted to a configured storage directory\n\n## Credits\n\n- **ISTAT API Wrapper**: This project relies on [istatapi](https://github.com/ondata/guida-api-istat) by [ondata](https://github.com/ondata), an excellent open-source Python wrapper for ISTAT's SDMX API\n- **Data Source**: [ISTAT (Istituto Nazionale di Statistica)](https://www.istat.it/) - Italian National Institute of Statistics\n- **MCP Protocol**: [Anthropic's Model Context Protocol](https://modelcontextprotocol.io/)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Contributing\n\nContributions are welcome! We appreciate bug reports, feature requests, documentation improvements, and code contributions.\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:\n- Setting up your development environment\n- Running tests\n- Code style and conventions\n- Submitting pull requests\n\nQuick start for contributors:\n```bash\n# Fork and clone the repo\ngit clone https://github.com/YOUR_USERNAME/istat-mcp-server.git\ncd istat-mcp-server\n\n# Install dependencies\nuv sync\n\n# Run tests\nuv run pytest\n\n# Make your changes and submit a PR!\n```\n\n## Roadmap\n\nFuture enhancements planned:\n- [ ] Add caching for frequently accessed datasets\n- [ ] Support for more data export formats (CSV, JSON, Excel)\n- [ ] Integration with data visualization tools\n- [ ] Support for ISTAT time series analysis\n- [ ] Multi-language support (Italian/English metadata)\n\n## FAQ\n\n### How do I find the right dataset?\n\nUse the `search_datasets` tool with keywords like \"unemployment\", \"GDP\", \"population\", etc. The tool searches through all ISTAT dataset titles and descriptions.\n\n### Why am I getting a URL instead of data?\n\nFor 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.\n\n### Can I use this with other LLMs besides Claude?\n\nYes! Any MCP-compatible client can use this server. See the [MCP documentation](https://modelcontextprotocol.io/) for more information.\n\n### Where is the downloaded data stored?\n\nBy default:\n- WSL: `/mnt/c/Users/Public/Downloads/mcp-data/`\n- Windows: `%USERPROFILE%\\Downloads\\mcp-data`\n- Linux/macOS: `./data`\n\nYou can customize this with the `MCP_STORAGE_DIR` environment variable.\n\n## Changelog\n\nSee [Releases](https://github.com/Halpph/istat-mcp-server/releases) for version history and changes.\n\n## Support\n\nFor issues or questions:\n- Open an issue on [GitHub](https://github.com/Halpph/istat-mcp-server/issues)\n- Check [ISTAT API documentation](https://www.istat.it/en/web-services)\n- Refer to [istatapi guide](https://github.com/ondata/guida-api-istat)\n\n## Acknowledgments\n\n- **[ondata](https://github.com/ondata)** for the excellent [istatapi](https://github.com/ondata/guida-api-istat) Python wrapper\n- **[ISTAT](https://www.istat.it/)** for providing comprehensive statistical data about Italy\n- **[Anthropic](https://www.anthropic.com/)** for developing the Model Context Protocol\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol server for accessing Italian National Statistical Institute (ISTAT) data",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/Halpph/istat-mcp-server#readme",
"Homepage": "https://github.com/Halpph/istat-mcp-server",
"Issues": "https://github.com/Halpph/istat-mcp-server/issues",
"Repository": "https://github.com/Halpph/istat-mcp-server"
},
"split_keywords": [
"claude",
" data",
" istat",
" italy",
" llm",
" mcp",
" sdmx",
" statistics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "58fd5bb2546d79e9d91f08e9f5dc4443b2838eea551b97963ea0364053e35ef4",
"md5": "856e5c4a8b33f1c3eceb73b29a635cc5",
"sha256": "109c7d5368d2c50337385e19dffc4d7ec39c9586868d359d87d82fd2c854c032"
},
"downloads": -1,
"filename": "istat_mcp_server-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "856e5c4a8b33f1c3eceb73b29a635cc5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 170746,
"upload_time": "2025-10-14T12:43:47",
"upload_time_iso_8601": "2025-10-14T12:43:47.997580Z",
"url": "https://files.pythonhosted.org/packages/58/fd/5bb2546d79e9d91f08e9f5dc4443b2838eea551b97963ea0364053e35ef4/istat_mcp_server-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1b6e3cdb2074c230530d732f5be2b63cfb254e775055650751d2b7f3784daf11",
"md5": "44236977759713e60e91525404342689",
"sha256": "f76f478932eac2c9caa3a2460416ff7c3d89c7253feb100ec45c78c5012a22c3"
},
"downloads": -1,
"filename": "istat_mcp_server-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "44236977759713e60e91525404342689",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 155202,
"upload_time": "2025-10-14T12:43:49",
"upload_time_iso_8601": "2025-10-14T12:43:49.744507Z",
"url": "https://files.pythonhosted.org/packages/1b/6e/3cdb2074c230530d732f5be2b63cfb254e775055650751d2b7f3784daf11/istat_mcp_server-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 12:43:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Halpph",
"github_project": "istat-mcp-server#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "istat-mcp-server"
}
