mcp-csu

MCP server for the Czech Statistical Office (ČSÚ / CZSO) DataStat API. Gives AI assistants direct access to 700+ statistical datasets about the Czech Republic — population, economy, prices, wages, employment, industry, agriculture, trade, tourism, environment, and more.

Single Python file. No cloning required — just uvx mcp-csu.

Features

• Full catalog access — search, browse, and inspect all 700+ datasets and 1500+ predefined tables

• Data retrieval — fetch statistical data as CSV, query individual values with full context

• AI-optimized output — human-readable text for metadata, CSV for data, automatic truncation with row counts

• Rate limiting — built-in concurrency control (3 parallel requests) and minimum request interval (150ms)

• Caching — catalog listings cached in memory for 10 minutes to avoid redundant requests

• No authentication — the DataStat API is public

Prerequisites

• uv (Python package runner)

That's it. Python and all dependencies are managed automatically by uv.

Configuration

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "csu": {
      "command": "uvx",
      "args": ["mcp-csu"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "csu": {
      "command": "uvx",
      "args": ["mcp-csu"]
    }
  }
}

Any MCP client

The server uses stdio transport (default). Launch command:

uvx mcp-csu

Data model

The DataStat database has a hierarchical structure:

Dataset (sada)              e.g. CEN0101H — "Míra inflace"
├── Dimensions (dimenze)    e.g. CasR (years), Uz0 (territory)
│   └── Items (položky)     e.g. "2024", "CZ"
├── Indicators (ukazatele)  e.g. 6134J06 — "Průměrná roční míra inflace"
└── Selections (výběry)     e.g. CEN0101HT01 — "Průměrná roční míra inflace"
    └── CSV data            pre-configured table ready to fetch

Datasets contain raw multidimensional data. Each dataset has dimensions (time, territory, categories) and indicators (what is measured).

Selections are predefined views — a specific slice of a dataset with fixed dimension arrangement. They are the easiest way to get data.

Tools

Discovery

search_datasets

Full-text search across all datasets. Returns dataset codes, names, time period types, and territory levels.

search_datasets("inflace")
→ Found 3 dataset(s):
    WCEN01 (v4) — Index spotřebitelských cen (indexy, míra inflace)
    WCEN01M (v1) — Index spotřebitelských cen — měsíční data
    CEN0101H (v1) — Míra inflace

search_selections

Full-text search across all predefined data tables.

search_selections("mzdy")
→ Found 30 selection(s):
    MZDQ1T1 — Průměrný evidenční počet zaměstnanců a průměrné hrubé měsíční mzdy...
      Period: Čtvrtletí | Territory: Stát | Dataset: MZDQ1

list_datasets

Paginated listing of all datasets.

list_selections

Paginated listing of all predefined tables.

Exploration

get_dataset

Full dataset metadata: dimensions with item counts, indicators with definitions, keywords, update frequency.

get_dataset("CEN0101H")
→ Dataset: CEN0101H (v1)
  Name: Míra inflace
  Keywords: míra inflace
  Update frequency: MONTHLY

  Dimensions (4):
    CasM — Měsíce (720 items)
    CasR — Roky (61 items)
    CASRMX — Měsíce, roky (780 items)
    Uz0 — Území (1 items)

  Indicators (4):
    6134J09 — Přírůstek průměrného ročního indexu spotřebitelských cen - měsíční
    6134J06 — Průměrná roční míra inflace
    ...

get_dataset_selections

List predefined data tables for a specific dataset.

get_dataset_selections("CEN0101H")
→ Selections for CEN0101H (2):
    CEN0101HT01 — Průměrná roční míra inflace
      Period: Rok | Territory: Stát
    CEN0101HT02 — Míra inflace - měsíční
      Period: Měsíc | Territory: Stát

get_dimension_items

Get all possible values for a dimension. Supports hierarchy level filtering and pagination.

get_dimension_items("UZ023H2U", level="KRAJ")
→ Dimension UZ023H2U — 14 item(s) at level KRAJ:
    CZ010 — Hlavní město Praha (Capital City Prague) [KRAJ]
    CZ020 — Středočeský kraj (Central Bohemian Region) [KRAJ]
    CZ031 — Jihočeský kraj (South Bohemian Region) [KRAJ]
    ...

get_indicator

Indicator definition and display format.

Data retrieval

get_selection_data

Primary data access tool. Fetches CSV data from a predefined selection.

get_selection_data("CEN0101HT01", max_rows=5)
→ "Ukazatel","Území","Roky","Hodnota"
  "Průměrná roční míra inflace","Česko","2025","2.5"
  "Průměrná roční míra inflace","Česko","2024","2.4"
  "Průměrná roční míra inflace","Česko","2023","10.7"
  "Průměrná roční míra inflace","Česko","2022","15.1"
  "Průměrná roční míra inflace","Česko","2021","3.8"

  [Showing 5 of 29 rows. Use max_rows=0 for all data or max_rows=10 to see more.]

get_value

Retrieve a single specific value. The most precise query — returns one number with full context (indicator name, dimension labels, publication date).

get_value("RSO01", "3971b",
          ["CasR", "TYPPROSJED", "UZ023H2U"],
          ["2023", "501", "CZ"])
→ Value: 6 258
  Indicator: Počet územních jednotek
    Roky: 2023
    Typ prostorové jednotky: Obec
    ČR, kraje, okresy: Česko
  Published: 2024-04-30T07:00:00Z

custom_query

Execute an arbitrary data query on a dataset. Returns CSV.

This is an advanced tool — prefer get_selection_data() when a suitable predefined table exists. The custom query API is sensitive to correct dimension placement and hierarchy level filtering.

get_dataset_metadata

Dataset content statistics: record count, time range, publication and update timestamps.

Usage examples

Get Czech inflation rate

1. search_datasets("inflace")
   → CEN0101H — Míra inflace

2. get_dataset_selections("CEN0101H")
   → CEN0101HT01 — Průměrná roční míra inflace

3. get_selection_data("CEN0101HT01")
   → CSV with annual inflation rates from 1994 to present

Find average wages by region

1. search_selections("mzdy kraje")
   → MZDQ1T2 — ... dle krajů a regionů soudržnosti

2. get_selection_data("MZDQ1T2", max_rows=20)
   → CSV with wages by region

Get exact population of Prague in 2023

1. search_datasets("obyvatelstvo")
   → OBY01 — Obyvatelstvo podle pohlaví a věku

2. get_dataset("OBY01")
   → see dimensions and indicators

3. get_dimension_items("<territory_dim>", level="KRAJ")
   → find Prague code

4. get_value("OBY01", "<indicator>",
             ["<time_dim>", "<territory_dim>"],
             ["2023", "<prague_code>"])
   → exact value

Czech vocabulary for search

The database is in Czech. Common search terms:

Technical details

Architecture

Single-file Python server using FastMCP framework over stdio transport. Dependencies managed via PEP 723 inline script metadata — uv run installs them automatically into an isolated environment.

Upstream API

The server wraps two DataStat REST APIs:

API documentation:

• General info

• Catalog Swagger

• Data Swagger

Rate limiting

The DataStat API does not document rate limits, but the server applies conservative throttling:

• Max concurrent requests: 3 (semaphore)

• Min request interval: 150ms (global)

• Request timeout: 60 seconds

Caching

Catalog listings (list_datasets, list_selections) are cached in memory with a 10-minute TTL. These endpoints return the full catalog (700–1500 items) on every call since the API ignores pagination parameters — caching avoids repeated large transfers.

Output formatting

• Metadata tools return structured text with clear labels

• Data tools return CSV (most compact and LLM-friendly tabular format)

• Truncation: data responses are limited to 100 rows by default, with total count shown. Adjustable via max_rows parameter

• Language: all API responses are in Czech (Accept-Language: cs)

Dependencies

Both installed automatically by uv run.

License

MIT