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.

Clone the repository:

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

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:

✅ Check for Node.js (requires version 18 or higher)
📦 Install all dependencies
🔨 Build the project
🔗 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

Install globally via npm from GitHub:

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

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

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

Method 4: Local Development Installation

Clone the repository:

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

Install dependencies:

npm install

Build the project:

npm run build

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 measures - essential for querying data.

Parameters:

dsd_id (required): Data Structure Definition ID (e.g., DSD_SUPPLY_USE_ENERGY)
agency_id (optional): Agency ID (default: SSSU)
version (optional): Version (default: latest)
references (optional): Include references - none, parents, children, descendants, all (default: descendants)

Example:

Get the data structure for DSD_SUPPLY_USE_ENERGY.

4. `get_concept_scheme`

Get concept scheme definitions.

Purpose: Understand the concepts used in statistical data.

Parameters:

concept_scheme_id (required): Concept Scheme ID
agency_id (optional): Agency ID (default: SSSU)
version (optional): Version (default: latest)

5. `list_codelists`

List all available codelists (controlled vocabularies).

Purpose: Discover available reference lists for dimensions (countries, indicators, etc.).

Parameters:

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

Example:

List all available codelists.

6. `get_codelist`

Get a specific codelist with all values and translations.

Purpose: Understand allowed values for dimensions (essential for filtering data).

Parameters:

codelist_id (required): Codelist ID (e.g., CL_SUPPLY_USE_ENERGY_INDICATOR)
agency_id (optional): Agency ID (default: SSSU)
version (optional): Version (default: latest)

Example:

Get the codelist CL_SUPPLY_USE_ENERGY_INDICATOR with all values.

7. `get_data`

Retrieve statistical data with flexible filtering.

Purpose: Get actual statistical time series and observations.

Parameters:

resource_id (required): Resource/dataflow ID
context (optional): Context type - dataflow, datastructure, provisionagreement (default: dataflow)
agency_id (optional): Agency ID (default: SSSU)
version (optional): Version (default: latest)
key (optional): Data key with wildcards (default: * for all data)
start_period (optional): Start time period (e.g., 2020-01)
end_period (optional): End time period (e.g., 2023-12)
dimension_filters (optional): Dimension filters as object (e.g., {"FREQ": "A", "INDICATOR": "ENERGY_PRODUCTION"})

Example:

Get annual energy data from DF_SUPPLY_USE_ENERGY for 2020 to 2023.

8. `check_data_availability`

Check what data is available without retrieving it.

Purpose: Explore available dimensions and values before querying large datasets.

Parameters:

resource_id (required): Resource/dataflow ID
context (optional): Context type (default: dataflow)
agency_id (optional): Agency ID (default: SSSU)
version (optional): Version (default: latest)
key (optional): Data key with wildcards (default: *)

Example:

Check data availability for DF_SUPPLY_USE_ENERGY.

Common Usage Workflows

Workflow 1: Exploring a New Dataset

List dataflows to find interesting datasets
```
List all dataflows
```
Get dataflow details to understand what the dataset contains
```
Get dataflow DF_SUPPLY_USE_ENERGY
```
Get data structure to see dimensions and attributes
```
Get data structure DSD_SUPPLY_USE_ENERGY
```
Get codelists to see allowed values for dimensions
```
Get codelist CL_SUPPLY_USE_ENERGY_INDICATOR
```

Retrieve data with appropriate filters

Get data from DF_SUPPLY_USE_ENERGY for 2020-2023

Workflow 2: Quick Data Retrieval

If you already know the dataflow ID:

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

The AI will use the appropriate tools to fetch the data.

Data Format

All responses are returned in JSON format, converted from the original SDMX XML responses. The JSON structure follows the SDMX standard with attributes prefixed with @_.

API Information

This MCP server uses the SDMX API v3 from:

API Documentation: https://stat.gov.ua/uk/development-api/sdmx-api-v3
Examples: https://stat.gov.ua/uk/development-api/step-by-step-example
Base URL: https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0

Troubleshooting

Server not appearing in Claude Desktop

Check that the path in claude_desktop_config.json is correct
Ensure you've built the project with npm run build
Restart Claude Desktop
Check Claude Desktop logs for errors

API Request Failures

The Ukrainian Statistics API may have rate limits
Some datasets might be temporarily unavailable
Network connectivity to stat.gov.ua is required

XML Parsing Errors

If you encounter XML parsing errors, the API response format may have changed. Please report this as an issue.

Development

Project Structure

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

Running in Development Mode

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

# In another terminal
node build/index.js

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Contact

For questions about the Ukrainian Statistics API, please visit the official documentation at https://stat.gov.ua/uk/development-api/

Ukrainian Statistics MCP Server

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

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.

Clone the repository:

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

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:

✅ Check for Node.js (requires version 18 or higher)
📦 Install all dependencies
🔨 Build the project
🔗 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

Install globally via npm from GitHub:

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

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

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

Method 4: Local Development Installation

Clone the repository:

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

Install dependencies:

npm install

Build the project:

npm run build

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 measures - essential for querying data.

Parameters:

dsd_id (required): Data Structure Definition ID (e.g., DSD_SUPPLY_USE_ENERGY)
agency_id (optional): Agency ID (default: SSSU)
version (optional): Version (default: latest)
references (optional): Include references - none, parents, children, descendants, all (default: descendants)

Example:

Get the data structure for DSD_SUPPLY_USE_ENERGY.

4. `get_concept_scheme`

Get concept scheme definitions.

Purpose: Understand the concepts used in statistical data.

Parameters:

concept_scheme_id (required): Concept Scheme ID
agency_id (optional): Agency ID (default: SSSU)
version (optional): Version (default: latest)

5. `list_codelists`

List all available codelists (controlled vocabularies).

Purpose: Discover available reference lists for dimensions (countries, indicators, etc.).

Parameters:

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

Example:

List all available codelists.

6. `get_codelist`

Get a specific codelist with all values and translations.

Purpose: Understand allowed values for dimensions (essential for filtering data).

Parameters:

codelist_id (required): Codelist ID (e.g., CL_SUPPLY_USE_ENERGY_INDICATOR)
agency_id (optional): Agency ID (default: SSSU)
version (optional): Version (default: latest)

Example:

Get the codelist CL_SUPPLY_USE_ENERGY_INDICATOR with all values.

7. `get_data`

Retrieve statistical data with flexible filtering.

Purpose: Get actual statistical time series and observations.

Parameters:

resource_id (required): Resource/dataflow ID
context (optional): Context type - dataflow, datastructure, provisionagreement (default: dataflow)
agency_id (optional): Agency ID (default: SSSU)
version (optional): Version (default: latest)
key (optional): Data key with wildcards (default: * for all data)
start_period (optional): Start time period (e.g., 2020-01)
end_period (optional): End time period (e.g., 2023-12)
dimension_filters (optional): Dimension filters as object (e.g., {"FREQ": "A", "INDICATOR": "ENERGY_PRODUCTION"})

Example:

Get annual energy data from DF_SUPPLY_USE_ENERGY for 2020 to 2023.

8. `check_data_availability`

Check what data is available without retrieving it.

Purpose: Explore available dimensions and values before querying large datasets.

Parameters:

resource_id (required): Resource/dataflow ID
context (optional): Context type (default: dataflow)
agency_id (optional): Agency ID (default: SSSU)
version (optional): Version (default: latest)
key (optional): Data key with wildcards (default: *)

Example:

Check data availability for DF_SUPPLY_USE_ENERGY.

Common Usage Workflows

Workflow 1: Exploring a New Dataset

List dataflows to find interesting datasets
```
List all dataflows
```
Get dataflow details to understand what the dataset contains
```
Get dataflow DF_SUPPLY_USE_ENERGY
```
Get data structure to see dimensions and attributes
```
Get data structure DSD_SUPPLY_USE_ENERGY
```
Get codelists to see allowed values for dimensions
```
Get codelist CL_SUPPLY_USE_ENERGY_INDICATOR
```

Retrieve data with appropriate filters

Get data from DF_SUPPLY_USE_ENERGY for 2020-2023

Workflow 2: Quick Data Retrieval

If you already know the dataflow ID:

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

The AI will use the appropriate tools to fetch the data.

Data Format

All responses are returned in JSON format, converted from the original SDMX XML responses. The JSON structure follows the SDMX standard with attributes prefixed with @_.

API Information

This MCP server uses the SDMX API v3 from:

API Documentation: https://stat.gov.ua/uk/development-api/sdmx-api-v3
Examples: https://stat.gov.ua/uk/development-api/step-by-step-example
Base URL: https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0

Troubleshooting

Server not appearing in Claude Desktop

Check that the path in claude_desktop_config.json is correct
Ensure you've built the project with npm run build
Restart Claude Desktop
Check Claude Desktop logs for errors

API Request Failures

The Ukrainian Statistics API may have rate limits
Some datasets might be temporarily unavailable
Network connectivity to stat.gov.ua is required

XML Parsing Errors

If you encounter XML parsing errors, the API response format may have changed. Please report this as an issue.

Development

Project Structure

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

Running in Development Mode

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

# In another terminal
node build/index.js

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Contact

For questions about the Ukrainian Statistics API, please visit the official documentation at https://stat.gov.ua/uk/development-api/

Ukrainian Statistics MCP Server

Ukrainian Statistics MCP Server

Features

Installation

Method 1: Install from npm (Recommended)

Method 2: Quick Install Using Install Scripts

Method 3: Install from GitHub

Method 4: Local Development Installation

Available Tools

1. list_dataflows

2. get_dataflow

3. get_data_structure

4. get_concept_scheme

5. list_codelists

6. get_codelist

7. get_data

8. check_data_availability

Common Usage Workflows

Workflow 1: Exploring a New Dataset

Workflow 2: Quick Data Retrieval

Data Format

API Information

Troubleshooting

Server not appearing in Claude Desktop

API Request Failures

XML Parsing Errors

Development

Project Structure

Running in Development Mode

License

Contributing

Contact

Ukrainian Statistics MCP Server

Features

Installation

Method 1: Install from npm (Recommended)

Method 2: Quick Install Using Install Scripts

Method 3: Install from GitHub

Method 4: Local Development Installation

Available Tools

1. list_dataflows

2. get_dataflow

3. get_data_structure

4. get_concept_scheme

5. list_codelists

6. get_codelist

7. get_data

8. check_data_availability

Common Usage Workflows

Workflow 1: Exploring a New Dataset

Workflow 2: Quick Data Retrieval

Data Format

API Information

Troubleshooting

Server not appearing in Claude Desktop

API Request Failures

XML Parsing Errors

Development

Project Structure

Running in Development Mode

License

Contributing

Contact

1. `list_dataflows`

2. `get_dataflow`

3. `get_data_structure`

4. `get_concept_scheme`

5. `list_codelists`

6. `get_codelist`

7. `get_data`

8. `check_data_availability`

1. `list_dataflows`

2. `get_dataflow`

3. `get_data_structure`

4. `get_concept_scheme`

5. `list_codelists`

6. `get_codelist`

7. `get_data`

8. `check_data_availability`