Ukrainian Statistics MCP Server

乌克兰统计MCP服务器

🇺🇦 中文版本

一个模型上下文协议（MCP）服务器，通过其SDMX API v3为人工智能模型提供对乌克兰国家统计局乌克兰统计数据的无缝访问。

特性

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

安装

方法1：从npm安装（推荐）

安装MCP服务器最简单的方法是通过npm：

npm install -g ukrainian-stats-mcp-server

安装后，添加到Claude Desktop配置：

视窗: %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使用用户目录。

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

在本地安装最简单的方法是使用提供的安装脚本。这些脚本会自动安装依赖项，构建项目，并使命令全局可用。

1. 克隆仓库:

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

1. 运行安装脚本:

Windows（PowerShell）:

.\install.ps1

Windows（命令提示符）:

install.bat

Linux/macOS:

chmod +x install.sh
./install.sh

安装脚本将：

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

运行安装脚本后，将以下内容添加到Claude Desktop配置中：

视窗: %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使用用户目录（脚本将提供说明）。

方法3：从GitHub安装

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

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

1. 添加到Claude桌面配置:

视窗: %APPDATA%\Claude\claude_desktop_config.json\ macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

1. 重新启动克劳德桌面 -服务器将准备就绪！

方法4：本地开发安装

1. 克隆仓库:

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

1. 安装依赖项:

npm install

1. 构建项目:

npm run build

1. 添加到Claude桌面配置 （使用绝对路径）：

{
  "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：探索新数据集

1. 列出数据流 查找有趣的数据集

   List all dataflows

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

   Get dataflow DF_SUPPLY_USE_ENERGY

1. 获取数据结构 查看尺寸和属性

   Get data structure DSD_SUPPLY_USE_ENERGY

1. 获取代码列表 查看尺寸的允许值

   Get codelist CL_SUPPLY_USE_ENERGY_INDICATOR

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

   Get data from DF_SUPPLY_USE_ENERGY for 2020-2023

工作流程2：快速数据检索

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

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

人工智能将使用适当的工具来获取数据。

数据格式

所有响应均以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. 重新启动克劳德桌面
4. 检查Claude Desktop日志是否有错误

API请求失败

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

XML解析错误

如果遇到XML解析错误，API响应格式可能已更改。请将此作为问题报告。

发展

项目结构

stat-mcp/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── api-client.ts         # Ukrainian Stats API client
│   └── tools/
│       ├── dataflows.ts      # Dataflow tools
│       ├── data-structures.ts # DSD and concept scheme tools
│       ├── codelists.ts      # Codelist tools
│       └── data.ts           # Data retrieval tools
├── build/                    # Compiled JavaScript (generated)
├── package.json
└── tsconfig.json

以开发模式运行

# Watch mode - auto-rebuild on changes
npm run watch

# In another terminal
node build/index.js

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交问题或拉取请求。

联系

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