AI导哈

意大利国家统计服务器

一个为AI助手提供实时访问意大利国家统计数据的MCP服务器，无需API密钥即可连接4700多个数据集。

  • by SimonBerg255
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 SimonBerg255/istat-mcp

使用说明

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 8000

MCP端点： 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} --时间序列数据

许可证

麻省理工学院——见 许可证.

相关 MCP