io.github.cyanheads/openaq-mcp-server

---

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

Tool	Description
openaq_find_locations	Find monitoring stations near a point, in a bounding box, or by country. The required first step — readings and measurements key on the location id this returns.
openaq_get_readings	Latest measured value for every sensor at a station, joined with its pollutant and unit. The current-conditions tool.
openaq_get_measurements	Historical series for one pollutant at one station over a date range, with raw/hourly/daily aggregation. Large ranges spill to a DataCanvas.
openaq_list_parameters	Catalog of measurable pollutants and their canonical units. The unit-disambiguation reference.
openaq_list_countries	Catalog of country-level coverage — data span and parameters measured, filterable by parametersId. An availability check before a regional sweep.
openaq_dataframe_describe	List the tables and columns staged on a DataCanvas so you can write valid SQL.
openaq_dataframe_query	Run a read-only SELECT over staged measurement series.

Resources

Resource	Description
openaq://location/{locationId}	Location metadata for a known location id — name, coordinates, country, provider, sensors (each with parameter + unit), and data span.
openaq://parameters	Full pollutant + unit catalog (same data as openaq_list_parameters).

All resource data is also reachable via tools — both resources mirror tool output, so tool-only MCP clients lose nothing.

Capability reference

openaq_find_locations _tool

• 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 further pages — distance ordering applies within a page, not across pages
• Returns each station's id, name, coordinates, distance (coordinate search only), country, provider, isMonitor/isMobile, its parameters 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-mcp-server air-quality tool

---

openaq_get_readings _tool

• Pass a locationId from openaq_find_locations, or coordinates + parametersId to auto-resolve the nearest station (within 25km) that measures that parameter
• Joins the latest feed (keyed only by sensor id) 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

---

openaq_get_measurements _tool

• Pass a locationId and parametersId; the server resolves the underlying sensor internally (v3 series are sensor-scoped)
• aggregation: raw (every reported value), hourly, or daily — rollups add a per-bucket min/median/max/mean/sd
• datetimeFrom/datetimeTo accept a date (YYYY-MM-DD) or full UTC timestamp; omit either for the most recent values or "up to now"
• Values carry their unit; the server never converts between µg/m³, ppm, and ppb
• Internal paging caps at 5000 rows and also stops on a failed page — pulledCount and pullComplete say what was actually collected, and totalCount is published as a floor (flagged by totalCountIsLowerBound) when OpenAQ answers the range with a ">N" bound instead of an exact count
• Past the 100-row inline preview, series is a preview and the pulled rows stage on a DataCanvas (canvasId + tableName) when CANVAS_PROVIDER_TYPE=duckdb — without it, the response still returns the preview plus a notice. Every row the response carries is rendered in the text output too, so a text-only client sees the same set
• Pass a prior canvas_id to put this series on that canvas whatever its size, for cross-station JOIN/UNION queries. Reuse stages one table per sensor: a different sensor adds a table, while re-staging the same sensor overwrites its earlier series and the response says so

---

openaq_list_parameters _tool

• Optional query filters the ~44-parameter catalog by code, display name, or description (case-insensitive); pollutantsOnly excludes meteorological/particle-count channels (temperature, humidity, wind, pressure)
• The unit-disambiguation reference — the same pollutant appears under multiple ids for different units (e.g. CO is id 4 in µg/m³, id 8 in ppm, id 102 in ppb)
• Returns each parameter's id, code, display name, canonical unit, and a one-line description

---

openaq_list_countries _tool

• Optional query matches a two-letter input as an exact ISO 3166-1 alpha-2 code, longer input as a substring of code or name; parametersId filters to countries measuring that parameter anywhere
• Returns each country's id, ISO code, name, datetimeFirst/datetimeLast data span, and the parameters measured anywhere within it
• The availability check before a regional openaq_find_locations sweep — answers "which countries have NO2 monitoring?"

---

openaq_dataframe_describe _tool

• Takes a canvas_id returned by a prior openaq_get_measurements call
• Returns each staged measurements_<sensorId> table with its row count and column names
• Throws canvas_unavailable when CANVAS_PROVIDER_TYPE is not duckdb

---

openaq_dataframe_query _tool

• Takes a canvas_id and a read-only SQL SELECT against the staged measurement tables
• Writes, DDL, and file/network table functions are rejected — only a single SELECT runs
• Responses carry at most 200 rows whatever the SQL shape; truncated reports that the cap bit, and the notice names ORDER BY <column> LIMIT 200 OFFSET <n> as the way to page the rest. rowCount is the rows returned, not the size of the full result
• Throws canvas_unavailable when DuckDB is off, or missing_table when the SQL references a table not staged on that canvas

---

openaq://location/{locationId} _resource

• Returns name, locality, timezone, country, provider, isMonitor/isMobile, coordinates, sensors (each with parameter id/name/unit), and the datetimeFirst/datetimeLast span
• locationId comes from openaq_find_locations
• Cached 5 minutes — station metadata is near-static, but datetimeLast advances as measurements land

---

openaq://parameters _resource

• Mirrors openaq_list_parameters with no query or filter — the full catalog
• Cached 1 hour — the catalog changes only when OpenAQ adds a parameter

DataCanvas spill workflow

A multi-month raw series can be thousands of rows — too large to inline without blowing context. When openaq_get_measurements stages a series, read the staged table with the two consumer tools, in this order:

Tool	Use
openaq_dataframe_describe	List staged tables and their columns (value, datetimeFrom, datetimeTo, min, median, max, avg, sd, percentComplete, flagged) — call first. The staged table is flat while the inline series is nested (summary.min), so SQL written from the response shape alone names columns that do not exist.
openaq_dataframe_query	Run a read-only SELECT for monthly means, exceedance counts, percentiles, or cross-sensor comparisons. Capped at 200 rows per response — aggregate in SQL, or page with ORDER BY plus LIMIT/OFFSET.

• The staging response names both tools and the table it wrote, so the handle is never opaque.
• One table per sensor (measurements_<sensorId>): reuse a canvas_id across two sensors to JOIN/UNION their series, and re-staging the same sensor overwrites its earlier table.
• Requires CANVAS_PROVIDER_TYPE=duckdb. Without it — or when a configured canvas fails to start — openaq_get_measurements still returns the preview plus a notice rather than dropping data already fetched.
• Not available in the .mcpb bundle — the Claude Desktop bundle ships without DuckDB's platform-specific native binding, since bundling it would lock the bundle to the OS it was packed on. Use the npm, npx, or Docker install for canvas work.

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:

• Single typed client over the OpenAQ v3 REST API with X-API-Key auth, retry with rate-limit-calibrated backoff, and OpenAQ-specific error classification (clean-JSON 404 → NotFound; the Python-repr 422 body → ValidationError; the plain-text 500 on bad coordinates → transient ServiceUnavailable)
• Hides the v3 location → sensor → measurement hierarchy — openaq_get_measurements resolves a station + parameter to the underlying sensor; openaq_get_readings joins the latest feed against the sensor map so every value is labeled
• DataCanvas spillover for large measurement series, queryable with read-only DuckDB SQL
• Coordinates and radius are bounded in Zod at the edge — OpenAQ returns an opaque plain-text 500 for out-of-range input, so the server rejects it cleanly before the call

Agent-friendly output:

• Measured-vs-modeled framing in every discovery tool — an empty result is stated as no coverage, not clean air, with a pointer to the modeled fallback, so an agent never misreads sparse data as a clean reading
• Units travel with every value, never converted — the same pollutant has multiple parameter ids for different units, so parametersId is the precise selector and openaq_list_parameters maps pollutant + unit → id
• Chainable ids and staleness signals — location id → readings/measurements, sensor id → history; datetimeLast and per-value timestamps expose how fresh "latest" actually is
• Capped lists disclose truncation (totalCount, truncated) via framework enrichment, reaching both the structured and text output surfaces

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, with this client config:

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

Self-Hosted / Local

An OpenAQ v3 API key is required — sent as the X-API-Key header on every request. Get a free key from your OpenAQ Explorer account.

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"
      ]
    }
  }
}

To enable DataCanvas SQL over large measurement series, add "CANVAS_PROVIDER_TYPE": "duckdb" to env.

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 OPENAQ_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (Node.js v24+ also works at runtime).
• A free OpenAQ v3 API key — sign up at explore.openaq.org.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/openaq-mcp-server.git

2. Navigate into the directory:

cd openaq-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env and set OPENAQ_API_KEY

Configuration

All configuration is validated at startup via Zod schemas. Key environment variables:

Variable	Description	Default
OPENAQ_API_KEY	Required. OpenAQ v3 API key, sent as the X-API-Key header. A missing key surfaces as a clean startup error.	—
OPENAQ_API_BASE_URL	OpenAQ v3 API base URL. Override for a proxy or test mirror.	https://api.openaq.org/v3
CANVAS_PROVIDER_TYPE	Set to duckdb to enable DataCanvas SQL over large measurement series. Without it, large series return a truncated preview and the dataframe tools are inert.	none
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for the HTTP server.	3010
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (RFC 5424).	info
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  bun run rebuild
  bun run start:http   # or start:stdio
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t openaq-mcp-server .
docker run --rm -e OPENAQ_API_KEY=your-api-key -p 3010:3010 openaq-mcp-server

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/openaq-mcp-server. The @duckdb/node-api runtime dependency ships in the image, so DataCanvas works once CANVAS_PROVIDER_TYPE=duckdb is set. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
src/index.ts	createApp() entry point — registers tools/resources and inits the service + canvas.
src/config	Server-specific environment variable parsing and validation with Zod.
src/mcp-server/tools/definitions	Tool definitions (*.tool.ts) — five OpenAQ tools plus two dataframe_* tools.
src/mcp-server/resources/definitions	Resource definitions (*.resource.ts) — location and parameters mirrors.
src/services/openaq	OpenAQ v3 API client, request/auth/retry, and domain types.
tests/	Unit and integration tests mirroring src/.

Development guide

See CLAUDE.md / AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources in the createApp() arrays
• Wrap the OpenAQ API: validate raw → normalize to the domain type → return the output schema; surface units verbatim and never fabricate missing fields

Data & licensing

Air quality data served by this MCP server is sourced from the OpenAQ platform. Attribution to OpenAQ as the data source is required when using this server's output (OpenAQ Terms of Use).

OpenAQ aggregates measurements from hundreds of government agencies, research institutions, and other monitoring networks worldwide. Each of those upstream providers may publish its own attribution or licensing terms. The provider field returned by openaq_find_locations, openaq_get_readings, and the openaq://location/{locationId} resource identifies the originating network for each station. Downstream users are responsible for reviewing and complying with the terms of any provider whose data they use.

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.