Openaq MCP Server

@cyanheads/openaq-mcp-server Find air-quality monitoring stations, read latest sensor values, and pull historical pollutant series via MCP. STDIO or Streamable HTTP. 8 Tools (7 enabled by default) • 2 Resources

Public Hosted Server: https://openaq.caseyjhand.com/mcp

Overview

Measured air quality from the OpenAQ v3 API: physical-sensor observations from government reference monitors and research-grade sensors worldwide. Find monitoring stations, read current values, and pull historical pollutant series from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Resources

Both resources mirror tool output, so tool-only clients lose nothing.

Capability reference

openaq_find_locations tool

• Scope by coordinates with radius (metres, 1–25000, default 12000), bbox, and/or iso (a code from openaq_list_countries); at least one is required, and coordinates and bbox exclude each other. parametersId, monitor, mobile, and providersId narrow further; up to 100 stations per page (limit, default 20), 1-based page
• Each station carries id, distanceMeters (coordinate search only), provider/providerId, isMonitor/isMobile, its parameters with units, and the datetimeFirst/datetimeLast span; coordinates, country, and provider are null when OpenAQ lists none
• totalCount counts stations through the current page and is a floor when totalCountIsLowerBound is set; no match fails as no_locations_found, a page past the end as page_exhausted

openaq_get_readings tool

• A locationId, or coordinates plus parametersId to resolve the nearest station within 25 km that measures it (compared across up to 1,000 matching stations; a full 1,000 adds a notice); with locationId, parametersId optionally filters to one parameter
• One reading per sensor with value, unit, sensorId, and datetimeUtc/datetimeLocal, plus the station's provider, providerId, timezone, and datetimeLast
• Misses are typed: location_not_found, parameter_not_at_location (with the station's available ids), no_station_near_coordinates, no_recent_values

openaq_get_measurements tool

• Requires locationId and parametersId; datetimeFrom/datetimeTo accept UTC timestamps or station-local YYYY-MM-DD dates (UTC days when the station has no timezone). aggregation is raw (default), hourly, or daily; up to 5,000 rows per call
• Returns series, sensorId, pulledCount, pullComplete, effectiveRange, and station provider, providerId, and timezone. totalCount is a floor when totalCountIsLowerBound is set; rollups add summary statistics, gapCount, the first 20 missing intervals as gaps, and a notice when edge buckets are clipped
• Past 100 rows, series is a preview (truncated) and the pulled rows stage on a DataCanvas as measurements_ (canvasId, tableName) when CANVAS_PROVIDER_TYPE=duckdb; a supplied canvas_id stages onto that canvas at any size. One table per sensor: a second sensor adds a table to join against, and re-staging the same sensor overwrites its earlier series

openaq_list_parameters tool

• Optional case-insensitive query over code, display name, and description; pollutantsOnly drops meteorological and particle-count channels
• Rows carry id, name, displayName, unit, and description; one pollutant can appear under several ids by unit (CO is 4 in µg/m³, 8 in ppm, 102 in ppb)

openaq_list_countries tool

• Optional query (a two-letter value matches an ISO 3166-1 alpha-2 code first; otherwise code or name substrings match) and parametersId; up to 100 per page (limit, default 20), 1-based page
• Rows carry code (the iso value for openaq_find_locations), name, the datetimeFirst/datetimeLast span, and the parameters measured anywhere in the country; totalCount is the full filtered count

openaq_dataframe_describe tool

• Takes a canvas_id from openaq_get_measurements and returns each staged table's name, rowCount, and columns. Call it before openaq_dataframe_query: the staged table is flat (min, sd) while the inline series nests those under summary
• Fails as canvas_unavailable unless CANVAS_PROVIDER_TYPE=duckdb, or canvas_not_found for an unknown or expired id

openaq_dataframe_query tool

• A canvas_id and one read-only SELECT; writes, DDL, and file/network table functions are rejected
• At most 200 rows per response, with truncated set when the cap cut the result; page with ORDER BY plus LIMIT/OFFSET
• Fails as canvas_unavailable, canvas_not_found, or missing_table

openaq_dataframe_drop tool

• Registered only with OPENAQ_ENABLE_CANVAS_DROP=true; calls fail as canvas_unavailable unless CANVAS_PROVIDER_TYPE=duckdb. When disabled, the HTTP landing page shows the enable hint and tools/list omits the tool
• Takes a canvas_id and deletes that whole canvas, including all staged tables. Other agents sharing the id lose access; OpenAQ's source data is unaffected
• Returns the requested canvasId and dropped: true when deleted, false when no reachable canvas exists. With authentication off, callers share a tenant: anyone holding an id can delete its canvas when enabled

openaq://location/{locationId} resource

• application/json: name, locality, timezone, country, provider, isMonitor/isMobile, coordinates, sensors (each with parameterId and unit), and the datetimeFirst/datetimeLast span
• locationId comes from openaq_find_locations; cached 5 minutes

openaq://parameters resource

• application/json catalog, the same rows as an unfiltered openaq_list_parameters
• Cached 1 hour

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

OpenAQ-specific:

• One typed client over the OpenAQ v3 REST API: X-API-Key auth, retry with backoff, and typed upstream failures (invalid_api_key, rate_limited, upstream_timeout, upstream_error) on every OpenAQ call
• Hides the v3 location → sensor → measurement hierarchy: readings join the latest feed to the station's sensor map, and measurements resolve a station plus parameter to its sensor
• Coordinates and bbox corners are range-checked and contradictory search scopes rejected before any request reaches OpenAQ
• Large measurement series stage on a DataCanvas for read-only DuckDB SQL, one table per sensor, so two series on one canvas_id can be joined

Agent-friendly output:

• Measured, not modeled: a search with no station fails as no_locations_found or no_station_near_coordinates, stated as no coverage rather than clean air
• Units travel with every value and are never converted; parametersId selects pollutant and unit together
• Freshness and truncation are explicit: per-value timestamps and datetimeLast, and totalCount / truncated / notice on capped results

Getting started

Public Hosted Instance

A public instance is available at https://openaq.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{

"mcpServers": { "openaq-mcp-server": { "type": "streamable-http", "url": "https://openaq.caseyjhand.com/mcp" } } }

Self-Hosted / Local

Add the following to your MCP client configuration file.

{

"mcpServers": { "openaq-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/openaq-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "OPENAQ_API_KEY": "your-api-key" } } } }

Or with npx (no Bun required):

{

"mcpServers": { "openaq-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/openaq-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "OPENAQ_API_KEY": "your-api-key" } } } }

Or with Docker:

{

"mcpServers": { "openaq-mcp-server": { "type": "stdio", "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "OPENAQ_API_KEY=your-api-key", "ghcr.io/cyanheads/openaq-mcp-server:latest" ] } } }

Add `"CANVAS_PROVIDER_TYPE": "du