openaq-mcp-server wraps the OpenAQ v3 API to expose measured air quality — physical-sensor observations from government reference monitors and research-grade sensors worldwide. It is the ground-truth counterpart to a modeled air-quality grid: where a model gives a concentration anywhere, OpenAQ gives an actual reading from a physical monitor — sparser, unevenly distributed, but real.

Coverage is uneven and honest. An empty result means there is no monitoring there, not that the air is clean — every discovery tool says so, and points to a modeled fallback (open-meteo-mcp-server's air-quality tool) for anywhere-coverage.

Tools

Five domain tools cover the workflow — discover stations, read current values, pull history, and resolve the two catalogs (pollutant units, country coverage) — plus two DataCanvas tools for SQL over historical series too large to inline. The data model is location → sensor → parameter; the server hides the sensor layer so you think in stations and parameters, never sensor ids.

openaq_find_locations

Find air-quality monitoring stations (measured by physical sensors, not modeled) and the parameters each one reports.

• Three search scopes — coordinates + radius (near-me), bbox (area sweep), or iso country code; at least one is required
• radius is in metres, 1–25000 (the API hard-caps at 25000); larger areas need bbox, which returns no distance
• parametersId narrows to stations that measure a given parameter (each returned station still lists all its sensors)
• limit caps at 100 stations per page; page (1-based) reaches the rest — distance ordering applies within a page, not across pages, so paging is for iso/bbox sweeps rather than near-me searches
• coordinates and bbox accept whitespace around the commas — "47.6062, -122.3321" is normalized to its space-free form
• Returns each station's id, name, coordinates, distance (when searching by coordinates), country, provider, isMonitor/isMobile, the parameters its sensors measure with units, and the datetimeFirst/datetimeLast data span
• Empty result means no coverage, not clean air — widen the radius, check openaq_list_countries, or fall back to the modeled open-meteo air-quality tool

openaq_get_readings

Latest value per sensor at a station — the current-conditions tool.

• Pass a locationId from openaq_find_locations, or coordinates + parametersId to auto-resolve the nearest station (within 25km) that measures that parameter
• The raw OpenAQ latest feed is keyed only by sensor id; this tool joins it against the station's sensor → parameter → unit map, so every value carries its pollutant and unit
• With locationId, parametersId optionally filters the returned values to one parameter; omit it for all sensors
• Each value carries its UTC and local timestamp plus the station's datetimeLast — recency varies by station, so "latest" may be minutes or hours old

openaq_get_measurements

Historical measurement series for one pollutant at one station over a date range — for trend analysis and "was last week worse than the monthly average?".

• Pass a locationId and a parametersId and work in stations — the server maps station + parameter to the underlying sensor (v3 series are sensor-scoped), so you get the series for that pollutant at that station
• aggregation: raw (every reported value), hourly, or daily — hourly/daily add a per-bucket statistical summary (min, median, max, mean, sd)
• datetimeFrom/datetimeTo accept a date (YYYY-MM-DD) or full UTC timestamp (YYYY-MM-DDTHH:MM:SSZ); omit for the most recent values
• Values carry their unit; the server never converts between µg/m³, ppm, and ppb (the conversion is gas- and temperature-dependent)
• Large ranges spill to a DataCanvas — see below

DataCanvas spill workflow

A multi-month raw series can be thousands of rows — too large to inline without blowing context, and a fixed slice would blind the agent to the rest. When a series exceeds the inline preview (100 rows), openaq_get_measurements stages the pulled rows on a DuckDB-backed DataCanvas and returns:

• a preview (series, capped at 100 rows) plus rowCount and the totalCount enrichment,
• truncated: true, canvasId, and a tableName of the form measurements_<sensorId>.

The internal pager stops at 5000 rows, so the canvas holds the whole series only when totalCount is at or below that. Above it — or when a page fails partway and the rows already pulled are kept — the response carries a notice saying so and how to reach the rest (shorter date windows, or hourly/daily aggregation).

You then query the full set with the two consumer tools:

Pass a prior canvas_id back into openaq_get_measurements to stage a second station's series on the same canvas (as measurements_<otherSensorId>), then JOIN/UNION the two in one query to compare stations.

Requires CANVAS_PROVIDER_TYPE=duckdb. Without it, openaq_get_measurements still returns the truncated preview plus a notice (it does not fail), and the two dataframe tools return a canvas_unavailable error directing you to enable DuckDB. The same holds when the canvas is set to duckdb but cannot start — a missing DuckDB native in a .mcpb bundle, say: openaq_get_measurements returns the preview and names the staging failure in its notice rather than dropping a series it already fetched.

Not available in the .mcpb bundle. The Claude Desktop bundle ships without DuckDB's platform-specific native binding — including it would lock the bundle to the OS it was packed on and push it far past the size registries accept. Leave CANVAS_PROVIDER_TYPE at none there; use the npm, npx, or Docker install for canvas work.

openaq_dataframe_query is read-only by design — writes, DDL, and file/network table functions are rejected; only a single SELECT runs.

Resources and prompts