ISTAT MCP服务器
一 MCP（模型上下文协议） 服务器，让人工智能助手实时访问意大利国家统计数据 ISTAT （国家统计局） 通过公共 SDMX REST API。
将任何兼容MCP的人工智能助手连接到4700多个意大利统计数据集，涵盖人口统计、就业、教育、健康、经济、地区等，无需API密钥。
______________________________________________________________________
ISTAT是什么？
ISTAT是意大利国家统计局。它发布了以下方面的权威数据：
- 人口和人口统计（出生、死亡、移民、年龄结构）
- 就业和劳动力市场
- 教育和学校
- 健康和保健
- 市政财政和公共支出
- 住房和建筑
- 环境和领土
- 犯罪与司法
- 移民和外国居民
- 区域GDP和经济指标
数据门户： https://esploradati.istat.it
______________________________________________________________________
不需要API密钥
ISTAT SDMX REST API是完全公开的。无需注册或证书。
______________________________________________________________________
⚠️ 速率限制--请先阅读此内容
ISTAT强制每个IP地址每分钟5个请求的硬限制。
超过此值会触发持续1-2天的IP阻止。服务器通过滑动窗口自动执行速率限制。您将看到以下日志消息：
[ISTAT rate limit] Sleeping 12.3s to respect 5 req/min cap这是预期的行为。不要禁用速率限制器。
______________________________________________________________________
工具
服务器提供了四个通用工具，让AI代理浏览完整的ISTAT目录：
| 工具 | 目的 |
|---|---|
search_datasets | 按关键字搜索约4700个数据集。返回其他工具所需的数据集ID。 |
get_dataset_structure | 检查数据集的所有维度（例如地区、年龄、性别、时间频率）及其代码列表ID。第一次通话后缓存。 |
get_dimension_values | 查找任何维度的有效代码——地区名称、年龄组、性别代码等。通过 search= 过滤。缓存。 |
get_dataset_data | 使用由上述代码构建的点分隔键过滤器获取实际数据。 |
AI自动遵循的工作流程
1. search_datasets("unemployment by region") → get dataset ID
2. get_dataset_structure("151_914") → inspect dimensions, find codelist IDs
3. get_dimension_values("151_914", "REF_AREA", search="Lazio") → get territory code
4. get_dataset_data("151_914", key_filter="A.ITE4.......", last_n_observations=5)第2步和第3步是缓存的-每个数据集首次使用后没有额外的API调用。
______________________________________________________________________
资源
| URI | 描述 |
|---|---|
resource://istat/catalog | 公共部门使用的高价值数据集整理清单 |
resource://istat/api_guide | 速率限制规则、密钥过滤格式、已知错误、查询模式 |
______________________________________________________________________
本地运行
pip install -r requirements.txt
uvicorn server:app --host 0.0.0.0 --port 8000MCP端点： http://localhost:8000/mcp
健康检查： http://localhost:8000/health
______________________________________________________________________
示例问题
一旦连接，AI助手可以回答以下问题：
- *“米兰的人口是多少？”*
- *“给我看看卡拉布里亚过去5年的失业趋势。”*
- *“最近罗马有多少新生儿登记？”*
- *“意大利哪些地区的就业率最高？”*
- *“查找有关意大利入学率的数据集。”*
- *“比较北部地区的移民许可数据。”*
______________________________________________________________________
已知API行为
endPeriod 多退一年 --何时 endPeriod=2023 发送时，API将返回到2024的数据。此服务器自动应用解决方法（从请求的年终中减去1）。
API偶尔降解 --ISTAT的基础设施会定期出现速度减慢或部分中断，特别是在 /dataflow/IT1/all （目录）和 /data/... 端点。当这种情况发生时， search_datasets 和 get_dataset_data 将超时。元数据端点(get_dataset_structure, get_dimension_values)通常保持可用。恢复通常在几个小时到两天内。
______________________________________________________________________
建筑
- 框架: FastMCP python
- HTTP客户端:
httpx超时120秒verify=False（ISTAT SSL怪癖） - XML解析:
xml.etree.ElementTree（stdlib--无lxml） - 速率限制器：线程安全滑动窗口，每次请求前自动休眠
- 数据流缓存：完整目录提取一次，缓存24小时
- 结构缓存：每个数据集DSD无限期缓存在内存中
- 代码列表缓存：无限期缓存在内存中的每个代码列表值
______________________________________________________________________
SDMX API参考
基本URL: https://esploradati.istat.it/SDMXWS/rest/
使用的关键端点：
GET /dataflow/IT1/all--列出所有数据集GET /dataflow/IT1/{id}?references=all--数据集元数据+完整结构在一次调用中GET /codelist/IT1/{codelist_id}--尺寸的有效代码GET /data/IT1,{id},1.0/{key_filter}--时间序列数据
______________________________________________________________________
许可证
麻省理工学院——见 许可证.