gios-air-mcp
Query Poland’s GIOŚ air-quality monitoring data locally via MCP for stations, sensors, recent readings, and composite air index.
Search ~200 monitoring stations by city or voivodeship substring filters.
List sensors installed at a station, including pollutant indicators like PM2.5, PM10, NO2, SO2, O3, CO, and C6H6.
Fetch recent ~24 hours of measurements from a chosen sensor.
Get a station’s composite air-quality index category (Polish names) and critical pollutant code.
Use no API key; data comes from the public api.gios.gov.pl endpoint with hourly refresh per sensor.
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., "@gios-air-mcp How's the air in Kraków right now?"
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.
honest-gios-air-mcp
Local MCP server for the GIOŚ (Główny Inspektorat Ochrony Środowiska) air-quality public API — the official Polish state environmental monitoring feed for PM2.5, PM10, NO2, SO2, O3, CO, C6H6, and the composite air-quality index.
Part of the honest-mcp family of small, auditable, local-first MCP servers.
Why
If you live in a Polish city — especially over winter — the difference between "moderate" and "very poor" air-quality index matters (indoor training vs opening the window). GIOŚ runs close to 300 stations and a public API, but only in Polish JSON-LD. This server maps the main fields to English keys (see Output keys) and hands the data to your AI so you can ask "how's the air in Kraków this afternoon?"
Related MCP server: mcp-waqi
Features
Four tools:
list_stations— search the station network by city or voivodeshipget_station_sensors— list the sensors installed at a stationget_sensor_readings— recent measurements (~24h) from one sensorget_air_index— composite index for a station (very good / good / moderate / poor / very poor / hazardous; category names are returned in Polish) with the critical pollutant code
Output keys
Only some upstream Polish keys are mapped to English; the rest pass through unchanged, and values are never translated.
list_stations,get_sensor_readings— all fields use English keys.get_station_sensors— all fields use English keys (includingindicator_id).get_air_index— onlystation_id,index_calculated_at,index_source_data_at,index_categoryandcritical_pollutant_codeare English; all other fields — overall index value, per-pollutant fields (e.g.Wartość indeksu dla wskaźnika PM10) and the status flag — keep their Polish keys.Text values stay in Polish, e.g.
index_category: "Bardzo dobry"(very good) orindicator_name: "tlenek węgla"(carbon monoxide).
Data source
Endpoint: api.gios.gov.pl/pjp-api/v1 — GIOŚ public JSON-LD API
No API key
Refresh: hourly per sensor
Requirements
Python 3.10+
Setup
git clone https://github.com/bartosz-kuc/honest-gios-air-mcp.git
cd honest-gios-air-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txtOn Windows use venv\Scripts\pip and venv\Scripts\python.exe instead of the venv/bin/... paths shown here and below.
Register with Claude Code:
claude mcp add gios-air /absolute/path/to/venv/bin/python /absolute/path/to/server.pyClaude Desktop claude_desktop_config.json:
{
"mcpServers": {
"gios-air": {
"command": "/absolute/path/to/venv/bin/python",
"args": ["/absolute/path/to/server.py"]
}
}
}Example usage
"How's the air in Kraków right now?"
Two-step: list_stations(city="Kraków", limit=5) → pick a station ID → get_air_index(station_id=...) → category name (in Polish) and the critical pollutant code.
"PM2.5 readings for the last 24h from station 400."
get_station_sensors(station_id=400) → find the PM2.5 sensor ID → get_sensor_readings(sensor_id=...).
Data flow
Your AI client
↕ MCP stdio
This server (Python, on your machine)
↕ HTTPS
api.gios.gov.pl (GIOŚ)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
4 toolsget_air_indexB
Get the composite air-quality index for a station (aggregates all pollutants into a single category: very good / good / moderate / poor / very poor / hazardous).
Inputs: station_id (required).
get_sensor_readingsA
Get recent measurement readings from a sensor. Each reading is a (measured_at, value) pair. Returns latest ~24 hours.
Inputs: sensor_id (required).
get_station_sensorsA
List the sensors installed at a station (each sensor measures one pollutant/indicator such as PM10, PM2.5, NO2, SO2, O3, C6H6).
Inputs: station_id (required).
list_stationsA
List GIOŚ air-quality monitoring stations. Optional filters: city, voivodeship — both case-insensitive substring match. The full network is ~200 stations; use filters or limit to keep responses small.
Inputs: city, limit, voivodeship.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct resource and action: stations, sensors, readings, and air index. There is no overlap, and an agent can easily determine which tool to call for a given query.
All tool names follow a consistent verb_noun pattern (list_stations, get_station_sensors, get_sensor_readings, get_air_index). The naming is uniform, predictable, and uses clear, specific verbs.
With exactly 4 tools, the server is tightly scoped to air quality monitoring without redundancy. Each tool covers a necessary step in the workflow, making the count ideal for the domain.
The tool surface covers the full core workflow: discover stations, inspect sensors, fetch readings, and get an aggregated index. Minor gaps include lack of historical readings beyond 24 hours and no station metadata endpoint, but these are acceptable for a minimal yet functional set.
Maintenance
Related MCP Connectors
Access UK air quality data, monitoring sites, and hourly pollutant measurements across regions
Find air-quality stations and read pollutant observations from government monitors via OpenAQ v3.
Air quality in Poland: live GIOŚ measurements, smog warnings, CAMS forecast and pollen
Unofficial Air Quality MCP — wraps air-quality-api.open-meteo.com (free, no auth)
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables natural language interaction with air quality data from Airly, including real-time measurements, nearby stations, and forecasts.42 npmMIT
- AlicenseNot gradedqualityCmaintenanceProvides real-time Air Quality Index data from the World Air Quality Index service, enabling queries by location, station, or keyword search.310 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables querying real-time air quality measurements, integrated air quality index (CAI), and monitoring station information from Korea's Air Korea OpenAPI, including station search and nearby station lookup.MIT
- AlicenseNot gradedqualityCmaintenanceEnables querying global air-quality data from the OpenAQ API, including nearest-station readings, station discovery, latest pollutant values, and historical time series for sensors.149 npmMIT