ISTAT MCP 服务器
   
A. 模型上下文协议（MCP） 该服务器使大型语言模型能够直接访问并分析来自意大利国家统计局（ISTAT）的数据。
这是什么？
这个MCP服务器允许像Claude这样的大型语言模型（LLM）无缝查询、过滤和从ISTAT下载统计数据集，从而实现自然语言数据分析工作流程。您无需手动搜索数据集、构建API查询和下载数据，只需让您的大型语言模型查找并分析意大利统计数据即可。
建立在： 这台服务器采用了卓越的 istatapi（注：这是一个技术或编程相关的术语，直接翻译可能无具体含义，通常指与Windows API（应用程序编程接口）相关的某种状态或接口管理工具/库，但具体含义需结合上下文确定） 由ondata提供的开源Python封装工具，简化了与ISTAT SDMX REST API的交互。
特点/功能
- 数据集发现搜索并浏览所有可用的ISTAT数据集
- 维度探索检查数据集结构和可用过滤器
- 灵活的数据检索直接获取JSON格式的数据或下载大型数据集
- 智能错误处理在大文件/超时场景下自动回退到文件下载
- 安全存储可配置的存储目录，带有路径遍历保护
- 跨平台适用于WSL、Windows、macOS和Linux系统
用例
使您的大型语言模型（LLM）能够：
- 查找意大利经济指标（GDP、失业率、通货膨胀率）
- 分析人口趋势和人口统计数据
- 比较意大利各地区的数据
- 下载并处理大型统计数据集
- 从ISTAT数据创建数据可视化图表
- 自然流畅地回答有关意大利统计数据的问题
安装
快速入门（推荐）
使用这个MCP服务器最简单的方法是直接通过 uvx - 无需安装：
uvx istat-mcp-server从PyPI安装
# 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 .配置
Claude 桌面版安装
将此添加到您的Claude桌面配置文件中：
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"
}
}
}
}就是这么简单！Claude Desktop 将会自动从 PyPI 下载并运行服务器。
备选方案：从本地安装运行
如果您是从源代码安装或想运行开发版本：
{
"mcpServers": {
"istat": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/istat-mcp-server",
"run",
"istat-mcp-server"
],
"env": {
"MCP_STORAGE_DIR": "/path/to/data/storage"
}
}
}
}存储配置
默认情况下，下载的文件将保存到：
- WSL（Windows Subsystem for Linux）：
/mnt/c/Users/Public/Downloads/mcp-data/ - Windows:
%USERPROFILE%\Downloads\mcp-data - Linux/macOS（Linux/苹果操作系统）：
./data
通过设置此来覆盖它 MCP_STORAGE_DIR 环境变量。
其他环境变量
MCP_DEBUG设置为true在响应中提供详细的错误追踪信息
可用工具
数据集发现
get_list_of_available_datasets()- 列出所有可用的ISTAT数据集search_datasets(query)- 按关键词搜索数据集
数据集探索
get_dataset_dimensions(dataflow_identifier)- 获取数据集的维度/结构get_dimension_values(dataflow_identifier, dimension)- 获取维度的可能值
数据检索
get_data(dataflow_identifier, filters)- 获取带有过滤器的数据（如果数据量过大，则通过URL获取）get_data_limited(dataflow_identifier, filters, limit)- 获取有限数量的记录get_summary(dataflow_identifier, filters)- 获取过滤数据的统计摘要
文件操作
get_dataset_url(dataflow_identifier, filters)- 获取带有元数据的下载URLdownload_dataset(url, output_path)- 将数据集下载到本地存储
示例用法
使用Claude Desktop
一旦配置完成，您就可以自然地进行交互：
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
pytest项目结构
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其工作原理
- MCP协议服务器实现了模型上下文协议，将ISTAT数据操作作为大型语言模型（LLMs）可以调用的“工具”进行暴露
- ISTAT API 包装器使用 “istatapi”可以翻译为“统计API（应用程序编程接口）”。 用于与ISTAT的SDMX REST API交互的库
- 智能处理通过回退到文件下载方式，自动处理大型数据集
- 安全存储所有文件操作均限制在配置的存储目录内
功劳/学分/贡献
- 数据源： ISTAT（意大利国家统计局） - 意大利国家统计局
- MCP协议： Anthropic的模型上下文协议
许可证
MIT 许可证 - 详见 许可证 文件中有详细信息
做出贡献
欢迎贡献！我们非常感激您的错误报告、功能请求、文档改进以及代码贡献。
请看 \CONTRIBUTING.md\ 翻译成中文是“贡献指南文件（或：如何贡献文件）”。这个文件通常用于说明如何向某个项目或组织做出贡献，包括贡献的流程、规范、要求等 关于以下方面的详细指南：
- 设置您的开发环境
- 运行测试
- 代码风格和规范
- 提交拉取请求
为贡献者提供的快速入门指南：
# 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!路线图
计划中的未来改进：
- \[ \] 为频繁访问的数据集添加缓存
- \[ \] 支持更多数据导出格式（CSV、JSON、Excel）
- \[ \] 与数据可视化工具的集成
- \[ \] 支持ISTAT时间序列分析
- \[ \] 多语言支持（意大利语/英语元数据）
常见问题解答（FAQ）
我如何找到合适的数据集？
使用 search_datasets 一个包含“失业”、“GDP”、“人口”等关键词的工具。该工具会搜索所有ISTAT数据集的标题和描述。
为什么我得到的是URL而不是数据？
对于大型数据集或当API超时时，服务器会自动返回一个下载URL。然后您可以使用该 download_dataset 用于在本地保存数据的工具。
除了Claude之外，我还能用这个与其它大型语言模型（LLM）一起使用吗？
是的！任何兼容MCP的客户端都可以使用这个服务器。请参阅 MCP文档 如需更多信息。
下载的数据存储在哪里？
默认情况下：
- WSL：（Windows Subsystem for Linux，即Windows子系统对于Linux）
/mnt/c/Users/Public/Downloads/mcp-data/ - Windows：
%USERPROFILE%\Downloads\mcp-data - Linux/macOS：
./data
您可以根据这个进行自定义 MCP_STORAGE_DIR 环境变量。
更新日志
版本 0.1.2（2024年10月14日）
- 固定的自动文件格式检测
download_dataset函数
- 文件现在根据HTTP Content-Type头部信息保存了正确的扩展名 - 来自ISTAT API的XML/SDMX文件不再保存为.csv格式 - 增加了对XML、CSV、JSON、TXT以及未知格式的支持 - 现在的响应包括 detected_extension 并且 file_format 田野；领域；字段
- 测试为格式检测场景增加了全面的测试覆盖率
版本 0.1.1（2024年10月14日）
- 为跨平台兼容性（macOS、Windows、Linux、WSL）实现固定路径解析
- 更新后的文档
见 发布 以获取完整版本历史。
支持
对于问题或疑问：
- 在（某平台/项目）上提交一个问题
- 检查 ISTAT API文档
- 参考 ISTATAPI指南
致谢
- - “istata”可能是一个特定的名词或术语，具体含义需根据上下文确定，可能与统计、数据处理或某个特定领域相关。 - “api”在中文中通常翻译为“应用程序编程接口”（Application Programming Interface）。
- [](https://www.anthropic.com/) 因此，如果“istatapi”是“istata”和“api”的组合，那么它可能指的是某个特定领域（由“istata”指代）中的应用程序编程接口。不过，这只是一个基于字面拆解的推测，实际含义还需根据具体上下文来确定。在没有具体上下文的情况下，我们无法给出一个确切的中文翻译。