stat-gov-mcp
This server lets you search and retrieve Polish socioeconomic statistics from GUS BDL via MCP tools.
Search subject categories (e.g., prices, population) to anchor variable searches.
Find specific data series (variables) by name or subject.
Locate territorial units (voivodeships, powiats, gminas) by name and level.
Get full details for a given territorial unit.
Pull actual time-series data for a variable across chosen units and year range (default: all voivodeships).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@stat-gov-mcp Unemployment rate in Poland in 2024?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
stat-gov-mcp
Local MCP server for the Polish Central Statistical Office (GUS) Bank Danych Lokalnych (BDL) — the definitive public source for Polish socioeconomic statistics: population, prices, business demographics, unemployment, GDP, at country / voivodeship / powiat / gmina resolution.
Part of the honest-mcp family of small, auditable, local-first MCP servers.
Why
BDL contains tens of thousands of time series about Poland. Its web UI (bdl.stat.gov.pl) is powerful but slow to navigate when you know exactly what you want. The public REST API is the fast path but has enough concepts (subjects → variables → units → data) to make manual use annoying. This server lets your AI find the right variable and unit and pull the data — one conversation, done.
Same trust model as the rest of the family: data flows only between your machine and GUS.
Related MCP server: Tilastokeskus StatFin MCP Server
Features
Five tools:
search_subjects— browse or search the subject tree (e.g., "CENY", "LUDNOŚĆ")search_variables— find data series in a subjectsearch_units— find territorial units (voivodeship, powiat, gmina) by name and/or levelget_unit_details— full record for a unit IDget_data— pull actual values for a variable across chosen units and year range. Withunit_ids, only those units are returned (one API request per unit); without them, all voivodeships
Data source
Endpoint: bdl.stat.gov.pl/api/v1 — GUS BDL public REST API
No API key required; anonymous limits are 5 req/s, 100 per 15 min, 1,000 per 12 h and 10,000 per 7 days (api.stat.gov.pl)
get_datawithunit_idsmakes one request per unit (at most 4 req/s); on HTTP 429 it stops and lists the units it did not fetchHigher limits are available with free registration (API key); this server does not send a key, so it always uses the anonymous limits
Requirements
Python 3.10+
Setup
git clone https://github.com/bartosz-kuc/honest-stat-gov-mcp.git
cd honest-stat-gov-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txtOn Windows, use venv\Scripts\pip and venv\Scripts\python instead of the venv/bin/... paths here and below.
Register with Claude Code:
claude mcp add stat-gov /absolute/path/to/venv/bin/python /absolute/path/to/server.pyClaude Desktop claude_desktop_config.json:
{
"mcpServers": {
"stat-gov": {
"command": "/absolute/path/to/venv/bin/python",
"args": ["/absolute/path/to/server.py"]
}
}
}Example usage
"How has the average monthly wage changed in Mazowieckie over the last 10 years?"
Three-step: search_variables(name="przeciętne wynagrodzenie") → note variable ID → search_units(name="mazowieckie", level=2) → note unit ID → get_data(variable_id=..., unit_ids=[...], year_from=2015, year_to=2024) (with only year_from, just that one year is returned).
"Which voivodeships had the highest unemployment in 2024?"
search_variables(name="stopa bezrobocia") → get_data(variable_id=..., year_from=2024, year_to=2024) — default returns all voivodeships.
Data flow
Your AI client
↕ MCP stdio
This server (Python, on your machine)
↕ HTTPS
bdl.stat.gov.pl (GUS)No cloud middle. No telemetry.
Author
Bartosz Kuć — Warsaw-based developer, JDG owner running skanfirmy.pl.
GitHub: https://github.com/bartosz-kuc
Email: firma@bartosza.pl
Consulting
Available for consulting on Polish tax and business integrations (KSeF, GUS/NFZ/GIOŚ APIs, mBank data), MCP server design, and AI-assisted tooling for JDGs and small teams. See skanfirmy.pl/uslugi for productized packages (audit 3k PLN, setup 8-15k PLN, retainer 2-4k PLN/mo), or reach out via email.
License
MIT — see LICENSE.
Related
Part of the honest-mcp family — see the family index.
Available Tools
5 toolsget_dataA
Get actual data (time series) for a variable in one or more territorial units. Example: GDP per capita for all voivodeships over 2015-2024. Returns the raw values with year, unit, and unit label.
Inputs: variable_id (required), year_to, unit_ids, year_from, +1 more.
get_unit_detailsB
Get full details of a territorial unit by ID.
Inputs: unit_id (required).
search_subjectsA
Browse or search GUS BDL subject categories (top-level topics like 'CENY', 'LUDNOŚĆ', 'FINANSE PRZEDSIĘBIORSTW'). Use to discover subject IDs which then anchor variable searches.
Inputs: name, limit, parent_id.
search_unitsA
Search for territorial units by name — voivodeships, powiats, gminas. Returns unit IDs used with get_data. Level meanings: 0=Kraj (country), 2=Województwo, 5=Powiat, 6=Gmina.
Inputs: name (required), level, limit.
search_variablesA
Search for variables (data series) in GUS BDL. Variables are the atomic units of statistical data — each has an ID used with get_data. Filter by subject_id (from search_subjects) and/or name.
Inputs: name, limit, subject_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a clearly distinct entity or action: subjects, variables, units, unit details, and data. The descriptions cross-reference IDs and usage patterns, making it easy for an agent to select the right tool.
Tool names follow a consistent verb_noun pattern: search_subjects, search_variables, search_units, get_unit_details, get_data. All use lowercase snake_case and the prefixes search_ and get_ clearly distinguish discovery from retrieval.
Five tools is well-scoped for a statistical data access server. Each tool covers a necessary part of the browsing and data retrieval workflow without unnecessary or redundant additions.
The core workflow is complete: discover subjects, search variables, locate territorial units, get unit details, and fetch data. Minor gaps exist such as detailed variable metadata or subject detail endpoints, but they are not essential for typical data retrieval.
Maintenance
Related MCP Connectors
Experimental MCP exploring Polish administrative units and BDL statistics.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Unofficial Eurostat MCP — wraps Eurostat Statistical Data API (no auth required)
Experimental MCP exploring Statistics Finland PxWeb statistical datasets.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server providing AI assistants access to Polish public registries (KRS, CEIDG) and statistical data (GUS BDL) for querying companies, sole proprietorships, and regional statistics.7MIT
- AlicenseAqualityDmaintenanceProduction-grade MCP server for Statistics Finland's StatFin database. Enables AI assistants like Claude to browse, search, and query Finnish statistical data.712MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that enables querying Latvian official statistics from data.stat.gov.lv via PxWeb tables, allowing retrieval of table definitions and data through natural language or direct tool calls.70 npmMIT
- AlicenseAqualityDmaintenanceMCP server that provides AI agents with Polish business data tools: identifier validation (NIP, PESEL, REGON, KRS, IBAN), VAT whitelist checks, EU VIES lookups, and NBP exchange rates.511 npmMIT