Ukrainian Statistics

You can run the Ukrainian Statistics MCP Server locally to access official Ukrainian statistical data via the SDMX API v3. This server converts SDMX XML responses to JSON for easy consumption and provides flexible querying across multiple data domains while offering bilingual support.

How to use

You interact with this MCP server through your MCP client to list datasets, inspect data structures, and fetch observations. Typical workflows include discovering dataflows, inspecting their structure and codelists, and retrieving time series data with filters such as period range and dimension values. All responses arrive as JSON, making it straightforward to plug data into charts, dashboards, or analyses.

How to install

Prerequisites you need before installing:
- Node.js (version 18 or higher)
- npm (comes with Node.js) or an equivalent package manager
- A suitable environment to run commands in your operating system (Windows, macOS, or Linux)

Method 1: Install from npm (Recommended) - globally install the MCP server and configure Claude Desktop.

npm install -g ukrainian-stats-mcp-server

{
  "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 a user directory for npm or run the install with elevated privileges.

Method 2: Quick Install Using Install Scripts - clone the project, run the install script, and link the command globally.

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

Windows (PowerShell):

.\install.ps1

Windows (Command Prompt):

install.bat

Linux/macOS:

chmod +x install.sh ./install.sh

After installation, add to Claude Desktop configuration:

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

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

Method 3: Install from GitHub - install globally via npm from GitHub and configure Claude Desktop.

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

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

Restart Claude Desktop.

Method 4: Local Development Installation - build from source and run locally.

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

npm install

npm run build

Add to Claude Desktop configuration with the absolute path to the built index:

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

Run the server using the configured command after building.

Configuration and usage notes

The server is designed to work with MCP clients that support the MCP protocol. A typical local workflow involves starting the server and pointing your MCP client to the local command. You can adjust where Claude Desktop looks for the MCP by configuring the mcpServers entry as shown in the installation examples.

Data access is provided through the SDMX API v3 exposed by the Ukrainian Statistics Service. You will discover dataflows, retrieve data structures, and filter data using dimension keys and codelists. All data responses arrive as JSON after converting from the original SDMX XML.

Troubleshooting

If the MCP server does not appear in Claude Desktop, verify that the path in the Claude Desktop configuration is correct, ensure the project was built if you used a build step, and restart Claude Desktop. Check logs for errors.

API request failures may occur due to rate limits or temporary unavailability of datasets. Ensure network connectivity to the data source is active.

XML parsing errors can indicate changes in the API response format. If you encounter this, review the error details and reattempt the request after confirming the API structure.

Data format and API details

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

Base API URL for the service is the SDMX v3 endpoint and related examples are available from the Ukrainian statistics API docs.

Available tools

list_dataflows

List all available dataflows from the Ukrainian Statistics Service with optional detail level to explore domains such as energy, demographics, and trade.

get_dataflow

Get detailed information about a specific dataflow, including its structure and metadata.

get_data_structure

Retrieve the Data Structure Definition (DSD) for a dataset to understand dimensions, attributes, and measures.

get_concept_scheme

Fetch concept scheme definitions to understand the concepts used in the data.

list_codelists

List all available codelists for dimensions like countries and indicators.

get_codelist

Get a specific codelist with all values and translations to understand allowed dimension values.

get_data

Retrieve actual statistical data with flexible filtering across period ranges and dimension values.

check_data_availability

Check what data is available without retrieving it to explore dimensions and values.