\n\n[](https://github.com/cyanheads/openaq-mcp-server/releases/latest/download/openaq-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=openaq-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvb3BlbmFxLW1jcC1zZXJ2ZXIiXSwiZW52Ijp7Ik9QRU5BUV9BUElfS0VZIjoieW91ci1hcGkta2V5In19) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22openaq-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fopenaq-mcp-server%22%5D%2C%22env%22%3A%7B%22OPENAQ_API_KEY%22%3A%22your-api-key%22%7D%7D)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n`openaq-mcp-server` wraps the [OpenAQ v3 API](https://docs.openaq.org/) 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.\n\nCoverage 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`](https://github.com/cyanheads/open-meteo-mcp-server)'s air-quality tool) for anywhere-coverage.\n\n## Tools\n\nFive 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.\n\n| Tool | Description |\n|:---|:---|\n| `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. |\n| `openaq_get_readings` | Latest measured value for every sensor at a station, each joined with its pollutant and unit. The current-conditions tool. |\n| `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. |\n| `openaq_list_parameters` | Catalog of measurable pollutants and their canonical units. The unit-disambiguation reference. |\n| `openaq_list_countries` | Catalog of country-level coverage — data span and parameters measured, filterable by `parametersId` to answer \"which countries measure this pollutant?\". An availability check before a regional sweep. |\n| `openaq_dataframe_describe` | List the tables and columns staged on a DataCanvas so you can write valid SQL. |\n| `openaq_dataframe_query` | Run a read-only `SELECT` over staged measurement series. |\n\n### `openaq_find_locations`\n\nFind air-quality monitoring stations (measured by physical sensors, not modeled) and the parameters each one reports.\n\n- Three search scopes — `coordinates` + `radius` (near-me), `bbox` (area sweep), or `iso` country code; at least one is required\n- `radius` is in metres, 1–25000 (the API hard-caps at 25000); larger areas need `bbox`, which returns no distance\n- `parametersId` narrows to stations that measure a given parameter (each returned station still lists all its sensors)\n- `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\n- `coordinates` and `bbox` accept whitespace around the commas — `\"47.6062, -122.3321\"` is normalized to its space-free form\n- 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\n- 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\n\n---\n\n### `openaq_get_readings`\n\nLatest value per sensor at a station — the current-conditions tool.\n\n- Pass a `locationId` from `openaq_find_locations`, **or** `coordinates` + `parametersId` to auto-resolve the nearest station (within 25km) that measures that parameter\n- 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\n- With `locationId`, `parametersId` optionally filters the returned values to one parameter; omit it for all sensors\n- 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\n\n---\n\n### `openaq_get_measurements`\n\nHistorical measurement series for one pollutant at one station over a date range — for trend analysis and \"was last week worse than the monthly average?\".\n\n- 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\n- `aggregation`: `raw` (every reported value), `hourly`, or `daily` — `hourly`/`daily` add a per-bucket statistical summary (min, median, max, mean, sd)\n- `datetimeFrom`/`datetimeTo` accept a date (`YYYY-MM-DD`) or full UTC timestamp (`YYYY-MM-DDTHH:MM:SSZ`); omit for the most recent values\n- Values carry their unit; the server **never converts** between µg/m³, ppm, and ppb (the conversion is gas- and temperature-dependent)\n- **Large ranges spill to a DataCanvas** — see below\n\n### DataCanvas spill workflow\n\nA 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:\n\n- a preview (`series`, capped at 100 rows) plus `rowCount` and the `totalCount` enrichment,\n- `truncated: true`, `canvasId`, and a `tableName` of the form `measurements_`.\n\nThe 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).\n\nYou then query the full set with the two consumer tools:\n\n| Tool | Use |\n|:---|:---|\n| `openaq_dataframe_describe` | List staged tables and their columns (`value`, `datetimeFrom`, `datetimeTo`, `min`, `median`, `max`, `avg`, `sd`, `percentComplete`, `flagged`) — call this first to write SQL without guessing names. |\n| `openaq_dataframe_query` | Run a read-only `SELECT` for monthly means, exceedance counts, percentiles, or cross-sensor comparisons. |\n\nPass a prior `canvas_id` back into `openaq_get_measurements` to stage a **second** station's series on the same canvas (as `measurements_`), then `JOIN`/`UNION` the two in one query to compare stations.\n\n**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.\n\n**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.\n\n`openaq_dataframe_query` is read-only by design — writes, DDL, and file/network table functions are rejected; only a single `SELECT` runs.\n\n## Resources and prompts\n\n| Type | Name | Description |\n|:---|:---|:---|\n| Resource | `openaq://location/{locationId}` | Location metadata for a known location id — name, coordinates, country, provider, sensors (each with parameter + unit), and data span. |\n| Resource | `openaq://parameters` | Full pollutant + unit catalog (same data as `openaq_list_parameters`). |\n\nAll resource data is also reachable via tools — both resources mirror tool output, so tool-only MCP clients lose nothing. There are no prompts: this is a data-lookup domain with no recurring analysis template that earns one (a WHO-guideline health snapshot is a cross-server workflow, not localized here).\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Typed error contracts per tool — each network tool declares `reason`/`code`/`when`/`recovery`, so failures carry a concrete next move\n- Pluggable auth (`none`, `jwt`, `oauth`) and structured, request-scoped logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports from one codebase\n\nOpenAQ-specific:\n\n- 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`)\n- 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\n- DataCanvas spillover for large measurement series, queryable with read-only DuckDB SQL\n- 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\n\nAgent-friendly output:\n\n- **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\n- **Units travel with every value, never converted** — the same pollutant has multiple parameter ids for different units (`co` is id 4 µg/m³, id 8 ppm, id 102 ppb), so `parametersId` is the precise selector and `openaq_list_parameters` maps pollutant + unit → id\n- **Chainable ids and staleness signals** — location id → readings/measurements, sensor id → history; `datetimeLast` and per-value timestamps expose how fresh \"latest\" actually is\n- Capped lists disclose truncation (`totalCount`, `truncated`) via framework enrichment, reaching both the structured and text output surfaces\n\n## Getting started\n\n### Public Hosted Instance\n\nA 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:\n\n```json\n{\n \"mcpServers\": {\n \"openaq-mcp-server\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://openaq.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-hosted\n\nAn OpenAQ v3 API key is required — sent as the `X-API-Key` header on every request. Get a free key from your [OpenAQ Explorer](https://explore.openaq.org/) account.\n\nAdd the following to your MCP client configuration file.\n\n```json\n{\n \"mcpServers\": {\n \"openaq-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/openaq-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"OPENAQ_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"openaq-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/openaq-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"OPENAQ_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"openaq-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"-e\", \"OPENAQ_API_KEY=your-api-key\",\n \"ghcr.io/cyanheads/openaq-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nTo enable DataCanvas SQL over large measurement series, add `\"CANVAS_PROVIDER_TYPE\": \"duckdb\"` to `env`.\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 OPENAQ_API_KEY=your-api-key bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (Node.js v24+ also works at runtime).\n- A free OpenAQ v3 API key — sign up at [explore.openaq.org](https://explore.openaq.org/).\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/openaq-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd openaq-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env and set OPENAQ_API_KEY\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas. Key environment variables:\n\n| Variable | Description | Default |\n|:---|:---|:---|\n| `OPENAQ_API_KEY` | **Required.** OpenAQ v3 API key, sent as the `X-API-Key` header. A missing key surfaces as a clean startup error. | — |\n| `OPENAQ_API_BASE_URL` | OpenAQ v3 API base URL. Override for a proxy or test mirror. | `https://api.openaq.org/v3` |\n| `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` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n bun run rebuild\n bun run start:http # or start:stdio\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security, changelog sync\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t openaq-mcp-server .\ndocker run --rm -e OPENAQ_API_KEY=your-api-key -p 3010:3010 openaq-mcp-server\n```\n\nThe 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.\n\n## Project structure\n\n| Directory | Purpose |\n|:---|:---|\n| `src/index.ts` | `createApp()` entry point — registers tools/resources and inits the service + canvas. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools/definitions` | Tool definitions (`*.tool.ts`) — five OpenAQ tools plus two `dataframe_*` tools. |\n| `src/mcp-server/resources/definitions` | Resource definitions (`*.resource.ts`) — location and parameters mirrors. |\n| `src/services/openaq` | OpenAQ v3 API client, request/auth/retry, and domain types. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) / [`AGENTS.md`](./AGENTS.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources in the `createApp()` arrays\n- Wrap the OpenAQ API: validate raw → normalize to the domain type → return the output schema; surface units verbatim and never fabricate missing fields\n\n## Data & licensing\n\nAir quality data served by this MCP server is sourced from the [OpenAQ](https://openaq.org) platform. **Attribution to OpenAQ as the data source is required** when using this server's output ([OpenAQ Terms of Use](https://docs.openaq.org/about/terms)).\n\nOpenAQ 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.\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](./LICENSE) for details.\n",
"bytes": 19282,
"sha": "fae5c09497f8419d504b616cfa4291180cb8df5693b45faeb5180ff08db5eab4",
"repo_slug": "cyanheads/openaq-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_openaq_mcp_server_ad7a8d76/readme"
}