Skip to main content
Glama

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 voivodeship

  • get_station_sensors — list the sensors installed at a station

  • get_sensor_readings — recent measurements (~24h) from one sensor

  • get_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 (including indicator_id).

  • get_air_index — only station_id, index_calculated_at, index_source_data_at, index_category and critical_pollutant_code are 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) or indicator_name: "tlenek węgla" (carbon monoxide).

Data source

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.txt

On 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.py

Claude 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.

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.

Available Tools

4 tools
get_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

    A3.9/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables natural language interaction with air quality data from Airly, including real-time measurements, nearby stations, and forecasts.
      42 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT