# openaq-mcp-server [Health: Active]

**Category:** 🌳 Environment & Nature  
**Repository:** https://github.com/cyanheads/openaq-mcp-server  
**GitHub Stars:** 3  
**npm Downloads (last month):** 570  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/openaq-mcp-server

## Description
Find air-quality stations and read pollutant observations from government monitors via OpenAQ v3.

## Tools
Capabilities this server exposes over MCP:

- **openaq_find_locations** — Find monitoring stations near a point, in a bounding box, or by country; the location ids the other tools take
- **openaq_get_readings** — Latest value for every sensor at a station, labeled with its pollutant and unit
- **openaq_get_measurements** — Historical series for one pollutant at one station, raw or rolled up hourly/daily
- **openaq_list_parameters** — Pollutant catalog with canonical units; maps a pollutant and unit to its parameter id
- **openaq_list_countries** — Country coverage: data span and the parameters measured in each
- **openaq_dataframe_describe** — List the tables and columns staged on a DataCanvas
- **openaq_dataframe_query** — Run a read-only SQL `SELECT` over staged measurement series
- **openaq_dataframe_drop** — Delete a complete staged canvas; opt-in with `OPENAQ_ENABLE_CANVAS_DROP=true

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `bunx` (confidence: high):

```json
"mcpServers": {
  "openaq-mcp-server": {
    "command": "bunx",
    "args": ["@cyanheads/openaq-mcp-server@latest"],
    "env": {
      "OPENAQ_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `OPENAQ_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What openaq-mcp-server MCP server does

The openaq-mcp-server MCP server exposes OpenAQ v3 air-quality data to MCP clients. It can locate monitoring stations by coordinates, radius, bounding box, or country, then use the resulting location IDs to retrieve sensor data. Station results include provider details, coordinates when available, monitor or mobile status, measured parameters, and the available data span.

Current observations come from `openaq_get_readings`, which returns one latest value per sensor with pollutant labels, units, timestamps, and station metadata. For analysis over time, `openaq_get_measurements` retrieves a single pollutant series for a station. Results may be raw or aggregated hourly or daily, with range and gap information included for rolled-up data.

The server also provides parameter and country catalogs. These help an agent convert a pollutant and unit into the parameter ID required by measurement calls, or identify countries with coverage for a given parameter.

## Tools and capabilities

The openaq-mcp-server MCP server includes tools for:

- Finding stations using geographic filters, country codes, provider IDs, monitor status, mobile status, and parameter IDs.
- Reading the latest value from every sensor at a station, or resolving a nearby station for specified coordinates and a parameter.
- Retrieving up to 5,000 measurement rows per call with UTC or station-local date ranges.
- Listing pollutant definitions, canonical units, country coverage, measurement spans, and available parameters.
- Describing staged DataCanvas tables and columns.
- Running read-only SQL `SELECT` queries against staged measurement data.
- Optionally deleting an entire staged canvas when canvas deletion is enabled.

Two resources are also available: one exposes metadata for a location ID, and the other exposes the complete parameter and unit catalog. Clients that only support tools can use the equivalent tool output.

## How it works

Run the server as a stdio process, a local Streamable HTTP service, or use the public hosted MCP endpoint. The normal workflow is to search for a station, inspect its parameters, and pass the selected location and parameter IDs to a readings or measurements call. A coordinate-based readings request can instead find the nearest matching station within 25 kilometers.

Large measurement results are previewed in the direct response after the first 100 rows. When DuckDB canvas support is enabled, the pulled series is staged in a table named for its sensor. A caller can provide a canvas ID to place multiple sensor series together, describe the resulting tables, and query them with read-only SQL. Query responses are capped at 200 rows and can be paged with `ORDER BY`, `LIMIT`, and `OFFSET`.

## Setup and configuration

The package can be installed for MCP clients with `npx -y @cyanheads/openaq-mcp-server`. Set `OPENAQ_API_KEY` in the client configuration. The README also provides installation links for Claude Desktop, Cursor, and VS Code, along with a hosted endpoint at `https://openaq.caseyjhand.com/mcp`.

Canvas features require `CANVAS_PROVIDER_TYPE=duckdb`. The destructive canvas tool is registered only when `OPENAQ_ENABLE_CANVAS_DROP=true`; enabling it allows callers with a canvas ID to delete all staged tables in that canvas. The server supports Docker as well as the package-based installation described in the project materials.

## Limitations and notes

Station searches return at most 100 stations per page, while measurement calls return at most 5,000 rows. Counts may be lower bounds in some paginated or large-result responses. A historical series can be truncated in the inline response even though its rows have been staged for later querying.

DataCanvas IDs can expire, and canvas operations fail when the configured provider is unavailable. Dropping a canvas does not change OpenAQ source data, but it removes every staged table and affects other agents sharing that ID. When authentication is disabled, anyone holding the ID can delete the canvas if deletion is enabled. The service reports typed errors for missing stations, unavailable parameters, absent recent values, unknown canvases, and missing tables.

_Full upstream README: https://allmcps.com/mcp/openaq-mcp-server/readme_