星战科技xingzhan.cloud
返回市场
istat-MCP-服务器

istat-MCP-服务器

作者：Halpph2 星标更新：2025-10-14
安装使用来源：spider==github.com

项目介绍

ISTAT MCP Server

PyPI Tests License: MIT Python 3.10+

一个模型上下文协议（MCP）服务器，使大型语言模型能够直接访问和分析意大利国家统计局（ISTAT）的数据。

这是什么？

这个MCP服务器允许像Claude这样的大型语言模型无缝查询、过滤并下载ISTAT的统计数据集，从而实现自然语言数据分析流程。无需手动搜索数据集、构建API查询并下载数据，只需简单地询问你的大型语言模型来查找和分析意大利统计数据。

基于： 该服务器使用了由ondata开发的出色开源Python封装istatapi，简化了与ISTAT的SDMX REST API的交互。

特性

  • 数据集发现：搜索和浏览所有可用的ISTAT数据集
  • 维度探索：检查数据集结构和可用过滤器
  • 灵活的数据检索：直接获取JSON格式的数据或下载大型数据集
  • 智能错误处理：自动回退到文件下载以应对大型数据集或超时情况
  • 安全存储：可配置存储目录，并具有路径遍历保护
  • 跨平台：适用于WSL、Windows、macOS和Linux

使用场景

启用你的大型语言模型：

  • 查找意大利经济指标（GDP、失业率、通货膨胀）
  • 分析人口趋势和人口统计数据
  • 比较意大利各地区的数据
  • 下载和处理大型统计数据集
  • 根据ISTAT数据创建数据可视化
  • 自然地回答关于意大利统计数据的问题

安装

快速开始（推荐）

最简单的使用此MCP服务器的方法是直接使用uvx——无需安装：

uvx istat-mcp-server

从PyPI安装

# 使用pip
pip install istat-mcp-server

# 使用uv
uv pip install istat-mcp-server

从源码安装（用于开发）

# 克隆仓库
git clone https://github.com/Halpph/istat-mcp-server.git
cd istat-mcp-server

# 使用uv安装（推荐）
uv sync

# 或者使用pip安装
python -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
pip install -e .

配置

Claude Desktop设置

在Claude Desktop配置文件中添加以下内容：

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: /mnt/c/Users/Public/Downloads/mcp-data/
  • Windows: %USERPROFILE%\Downloads\mcp-data
  • Linux/macOS: ./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) - 获取带有元数据的下载URL
  • download_dataset(url, output_path) - 将数据集下载到本地存储

示例用法

使用Claude Desktop

配置完成后，你可以自然地进行交互：

你: "查找有关意大利失业率的数据集"

Claude: [使用search_datasets工具]
我找到了几个失业率数据集...

你: "获取2024年的月度失业率"

Claude: [使用get_dataset_dimensions, get_dimension_values, get_data工具]
这是2024年的失业率数据...

程序化用法

from mcp.client import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 连接到服务器
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:
        # 列出可用工具
        tools = await session.list_tools()

        # 调用一个工具
        result = await session.call_tool("search_datasets", {"query": "unemployment"})

开发

运行测试

# 使用uv
uv run pytest

# 使用pip
pytest

项目结构

istat-mcp-server/
├── main.py              # 主MCP服务器实现
├── test_main.py         # 综合测试套件
├── pyproject.toml       # 项目元数据和依赖项
├── uv.lock             # 依赖项锁定文件
├── README.md           # 此文件
├── CONTRIBUTING.md     # 贡献指南
├── LICENSE             # MIT许可证
├── docs/               # 额外文档
│   ├── TESTING.md     # 测试指南
│   └── ISTATAPI_REFERENCE.md  # API参考
├── examples/           # 示例配置
│   └── gemini-extension.json  # Gemini设置示例
└── .github/
    └── workflows/      # CI/CD流水线
        ├── test.yml   # 自动化测试
        └── release.yml # 发布自动化

工作原理

  1. MCP协议：服务器实现了模型上下文协议，将ISTAT数据操作作为“工具”暴露给大型语言模型调用
  2. ISTAT API封装：使用istatapi库与ISTAT的SDMX REST API交互
  3. 智能处理：自动处理大型数据集，通过回退到文件下载
  4. 安全存储：所有文件操作都限制在配置的存储目录内

致谢

许可证

MIT许可证 - 详情见LICENSE文件

贡献

欢迎贡献！我们感谢bug报告、功能请求、文档改进和代码贡献。

请参阅CONTRIBUTING.md以了解详细指南：

  • 设置开发环境
  • 运行测试
  • 代码风格和约定
  • 提交拉取请求

快速入门指南：

# 分叉并克隆仓库
git clone https://github.com/YOUR_USERNAME/istat-mcp-server.git
cd istat-mcp-server

# 安装依赖项
uv sync

# 运行测试
uv run pytest

# 修改代码并提交拉取请求！

发展路线图

未来增强计划：

  • 添加对频繁访问数据集的缓存支持
  • 支持更多数据导出格式（CSV、JSON、Excel）
  • 与数据可视化工具集成
  • 支持ISTAT时间序列分析
  • 多语言支持（意大利语/英语元数据）

常见问题

如何找到正确的数据集？

使用search_datasets工具并输入关键词如“失业率”、“GDP”、“人口”等。该工具会在所有ISTAT数据集标题和描述中进行搜索。

为什么我得到的是URL而不是数据？

对于大型数据集或API超时的情况，服务器会自动返回一个下载URL。然后你可以使用download_dataset工具将数据保存到本地。

我可以用这个和其他大型语言模型一起使用吗？

可以！任何兼容MCP的客户端都可以使用此服务器。更多信息请参阅MCP文档。

下载的数据保存在哪里？

默认情况下：

  • WSL: /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）
  • 更新了文档

查看发布历史以获取完整的版本历史。

支持

对于问题或疑问：

致谢