Ukrainian Stats MCP Server

🚀 乌克兰统计MCP服务器

这是一个模型上下文协议（MCP）服务器，可让AI模型通过乌克兰国家统计局（Державна служба статистики України）的SDMX API v3无缝访问乌克兰统计数据。

🚀 快速开始

本服务器能助力AI模型便捷访问乌克兰官方统计数据。你可按需选择以下安装方式，完成安装并配置到Claude Desktop后，重启Claude Desktop即可使用。

✨ 主要特性

• 🇺🇦 可访问乌克兰政府官方统计数据。
• 📊 支持多个统计领域（能源、人口统计、贸易等）。
• 🌐 提供双语支持（乌克兰语和英语）。
• 🔍 支持灵活的数据过滤和查询。
• 📈 可全面探索元数据（数据流、结构、代码表）。
• ⚡ 能快速将XML转换为JSON，便于数据使用。

📦 安装指南

方法一：通过npm安装（推荐）

通过npm安装MCP服务器是最简便的方式：

npm install -g ukrainian-stats-mcp-server

安装完成后，添加到Claude Desktop配置文件中：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ukrainian-stats": {
      "command": "ukrainian-stats-mcp"
    }
  }
}

重启Claude Desktop，即可开始使用服务器！

⚠️ 重要提示

在Linux/macOS系统中，若遇到权限问题，可能需要使用 sudo npm install -g ukrainian-stats-mcp-server 命令，或者将npm配置为使用用户目录。

方法二：使用安装脚本快速安装

使用提供的安装脚本可在本地轻松完成安装。这些脚本会自动安装依赖项、构建项目，并使命令全局可用。

1. 克隆仓库：

git clone https://github.com/VladyslavMykhailyshyn/ukrainian-stats-mcp-server.git
cd ukrainian-stats-mcp-server

2. 运行安装脚本：

• Windows (PowerShell)：

.\install.ps1

• Windows (命令提示符)：

install.bat

• Linux/macOS：

chmod +x install.sh
./install.sh

安装脚本会执行以下操作：

1. ✅ 检查Node.js（需要版本18或更高）。
2. 📦 安装所有依赖项。
3. 🔨 构建项目。
4. 🔗 将命令全局链接（使 ukrainian-stats-mcp 在系统范围内可用）。

运行安装脚本后，添加到Claude Desktop配置文件中：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ukrainian-stats": {
      "command": "ukrainian-stats-mcp"
    }
  }
}

然后重启Claude Desktop，即可开始使用服务器！

⚠️ 重要提示

在Linux/macOS系统中，若遇到权限问题，可能需要运行 sudo ./install.sh 命令，或者将npm配置为使用用户目录（脚本会提供相应说明）。

方法三：从GitHub安装

1. 通过npm从GitHub全局安装：

npm install -g git+https://github.com/VladyslavMykhailyshyn/ukrainian-stats-mcp-server.git

2. 添加到Claude Desktop配置文件：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ukrainian-stats": {
      "command": "ukrainian-stats-mcp"
    }
  }
}

3. 重启Claude Desktop - 服务器即可使用！

方法四：本地开发安装

1. 克隆仓库：

git clone https://github.com/VladyslavMykhailyshyn/ukrainian-stats-mcp-server.git
cd ukrainian-stats-mcp-server

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

4. 添加到Claude Desktop配置文件（使用绝对路径）：

{
  "mcpServers": {
    "ukrainian-stats": {
      "command": "node",
      "args": ["/absolute/path/to/ukrainian-stats-mcp-server/build/index.js"]
    }
  }
}

💻 使用示例

可用工具

1. list_dataflows

列出乌克兰统计局所有可用的数据流（数据集）。

• 用途：发现可用的统计领域（如能源、贸易、人口统计等）。
• 参数：
  • detail（可选）：详细程度 - full、allstubs 或 referencestubs（默认：full）
• 示例：

Please list all available dataflows from Ukrainian statistics.

2. get_dataflow

获取特定数据流的详细信息。

• 用途：了解特定数据集的结构和元数据。
• 参数：
  • dataflow_id（必需）：数据流标识符（如 DF_SUPPLY_USE_ENERGY）
  • agency_id（可选）：机构ID（默认：SSSU）
  • version（可选）：版本（默认：latest）
• 示例：

Get information about the DF_SUPPLY_USE_ENERGY dataflow.

3. get_data_structure

获取数据集的数据结构定义（DSD）。

• 用途：了解维度、属性和度量 - 这对查询数据至关重要。
• 参数：
  • dsd_id（必需）：数据结构定义ID（如 DSD_SUPPLY_USE_ENERGY）
  • agency_id（可选）：机构ID（默认：SSSU）
  • version（可选）：版本（默认：latest）
  • references（可选）：包含引用 - none、parents、children、descendants、all（默认：descendants）
• 示例：

Get the data structure for DSD_SUPPLY_USE_ENERGY.

4. get_concept_scheme

获取概念方案定义。

• 用途：理解统计数据中使用的概念。
• 参数：
  • concept_scheme_id（必需）：概念方案ID
  • agency_id（可选）：机构ID（默认：SSSU）
  • version（可选）：版本（默认：latest）

5. list_codelists

列出所有可用的代码表（受控词汇表）。

• 用途：发现维度（国家、指标等）的可用参考列表。
• 参数：
  • detail（可选）：详细程度 - full 或 allstubs（默认：full）
• 示例：

List all available codelists.

6. get_codelist

获取包含所有值和翻译的特定代码表。

• 用途：了解维度的允许值（对过滤数据至关重要）。
• 参数：
  • codelist_id（必需）：代码表ID（如 CL_SUPPLY_USE_ENERGY_INDICATOR）
  • agency_id（可选）：机构ID（默认：SSSU）
  • version（可选）：版本（默认：latest）
• 示例：

Get the codelist CL_SUPPLY_USE_ENERGY_INDICATOR with all values.

7. get_data

通过灵活的过滤条件检索统计数据。

• 用途：获取实际的统计时间序列和观测值。
• 参数：
  • resource_id（必需）：资源/数据流ID
  • context（可选）：上下文类型 - dataflow、datastructure、provisionagreement（默认：dataflow）
  • agency_id（可选）：机构ID（默认：SSSU）
  • version（可选）：版本（默认：latest）
  • key（可选）：带有通配符的数据键（默认：* 表示所有数据）
  • start_period（可选）：开始时间段（如 2020-01）
  • end_period（可选）：结束时间段（如 2023-12）
  • dimension_filters（可选）：维度过滤器对象（如 {"FREQ": "A", "INDICATOR": "ENERGY_PRODUCTION"}）
• 示例：

Get annual energy data from DF_SUPPLY_USE_ENERGY for 2020 to 2023.

8. check_data_availability

在不检索数据的情况下检查可用数据。

• 用途：在查询大型数据集之前探索可用的维度和值。
• 参数：
  • resource_id（必需）：资源/数据流ID
  • context（可选）：上下文类型（默认：dataflow）
  • agency_id（可选）：机构ID（默认：SSSU）
  • version（可选）：版本（默认：latest）
  • key（可选）：带有通配符的数据键（默认：*）
• 示例：

Check data availability for DF_SUPPLY_USE_ENERGY.

常见使用流程

流程一：探索新数据集

1. 列出数据流 以查找感兴趣的数据集

List all dataflows

2. 获取数据流详细信息 以了解数据集包含的内容

Get dataflow DF_SUPPLY_USE_ENERGY

3. 获取数据结构 以查看维度和属性

Get data structure DSD_SUPPLY_USE_ENERGY

4. 获取代码表 以查看维度的允许值

Get codelist CL_SUPPLY_USE_ENERGY_INDICATOR

5. 使用适当的过滤器检索数据

Get data from DF_SUPPLY_USE_ENERGY for 2020-2023

流程二：快速数据检索

如果你已经知道数据流ID：

Get energy supply and use data from DF_SUPPLY_USE_ENERGY for the last 3 years

AI将使用适当的工具来获取数据。

📚 详细文档

数据格式

所有响应均以JSON格式返回，由原始的SDMX XML响应转换而来。JSON结构遵循SDMX标准，属性以 @_ 为前缀。

API信息

此MCP服务器使用以下SDMX API v3：

• API文档：https://stat.gov.ua/uk/development-api/sdmx-api-v3
• 示例：https://stat.gov.ua/uk/development-api/step-by-step-example
• 基础URL：https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0

故障排除

服务器未在Claude Desktop中显示

1. 检查 claude_desktop_config.json 中的路径是否正确。
2. 确保已使用 npm run build 命令构建项目。
3. 重启Claude Desktop。
4. 检查Claude Desktop日志以查找错误信息。

API请求失败

• 乌克兰统计API可能存在速率限制。
• 某些数据集可能暂时不可用。
• 需要与 stat.gov.ua 建立网络连接。

XML解析错误

如果遇到XML解析错误，可能是API响应格式发生了变化。请将此问题作为一个issue进行报告。

开发

项目结构

stat-mcp/
├── src/
│   ├── index.ts              # 主MCP服务器入口点
│   ├── api-client.ts         # 乌克兰统计API客户端
│   └── tools/
│       ├── dataflows.ts      # 数据流工具
│       ├── data-structures.ts # DSD和概念方案工具
│       ├── codelists.ts      # 代码表工具
│       └── data.ts           # 数据检索工具
├── build/                    # 编译后的JavaScript（自动生成）
├── package.json
└── tsconfig.json

在开发模式下运行

# 监听模式 - 代码更改时自动重新构建
npm run watch

# 在另一个终端中运行
node build/index.js

📄 许可证

本项目采用MIT许可证。

贡献

欢迎贡献代码！请随时提交issue或pull request。

联系

有关乌克兰统计API的问题，请访问官方文档：https://stat.gov.ua/uk/development-api/