Ukrainian Statistics MCP Server

Ukrainian Statistics MCP Server

🇺🇦 Українська версія

A Model Context Protocol (MCP) server that provides AI models with seamless access to Ukrainian statistical data from the State Statistics Service of Ukraine (Державна служба статистики України) via their SDMX API v3.

Features

• 🇺🇦 Access to official Ukrainian government statistics
• 📊 Support for multiple statistical domains (energy, demographics, trade, etc.)
• 🌐 Bilingual support (Ukrainian and English)
• 🔍 Flexible data filtering and querying
• 📈 Comprehensive metadata exploration (dataflows, structures, codelists)
• ⚡ Fast XML-to-JSON conversion for easy data consumption

Installation

Method 1: Install from npm (Recommended)

The easiest way to install the MCP server is via npm:

npm install -g ukrainian-stats-mcp-server

After installation, add to Claude Desktop configuration:

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"
    }
  }
}

Restart Claude Desktop and you're ready to use the server!

Note: On Linux/macOS, if you encounter permission issues, you may need to use sudo npm install -g ukrainian-stats-mcp-server or configure npm to use a user directory.

Method 2: Quick Install Using Install Scripts

The easiest way to install locally is using the provided install scripts. These scripts automatically install dependencies, build the project, and make the command globally available.

1. Clone the repository:

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

2. Run the install script:

Windows (PowerShell):

.\install.ps1

Windows (Command Prompt):

install.bat

Linux/macOS:

chmod +x install.sh
./install.sh

The install scripts will:

1. ✅ Check for Node.js (requires version 18 or higher)
2. 📦 Install all dependencies
3. 🔨 Build the project
4. 🔗 Link the command globally (makes ukrainian-stats-mcp available system-wide)

After running the install script, add to Claude Desktop configuration:

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"
    }
  }
}

Then restart Claude Desktop and you're ready to use the server!

Note: On Linux/macOS, if you encounter permission issues, you may need to run sudo ./install.sh or configure npm to use a user directory (the script will provide instructions).

Method 3: Install from GitHub

1. Install globally via npm from GitHub:

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

2. Add to Claude Desktop configuration:

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

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

3. Restart Claude Desktop - The server will be ready to use!

Method 4: Local Development Installation

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Add to Claude Desktop configuration (use absolute path):

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

Available Tools

1. `list_dataflows`

List all available dataflows (datasets) from the Ukrainian Statistics Service.

Purpose: Discover what statistical domains are available (e.g., energy, trade, demographics).

Parameters:

• detail (optional): Level of detail - full, allstubs, or referencestubs (default: full)

Example:

Please list all available dataflows from Ukrainian statistics.

2. `get_dataflow`

Get detailed information about a specific dataflow.

Purpose: Understand the structure and metadata of a specific dataset.

Parameters:

• dataflow_id (required): The dataflow identifier (e.g., DF_SUPPLY_USE_ENERGY)
• agency_id (optional): Agency ID (default: SSSU)
• version (optional): Version (default: latest)

Example:

Get information about the DF_SUPPLY_USE_ENERGY dataflow.

3. `get_data_structure`

Get the Data Structure Definition (DSD) for a dataset.

Purpose: Understand dimensions, attributes, and me