
Openaq Mcp Server
io.github.cyanheads由 GitHub 帳號 cyanheads 發布v0.4.1更新於 Oct 24, 2026
Find air-quality stations and read pollutant observations from government monitors via OpenAQ v3.
概覽
一個 OpenAQ v3 MCP 伺服器,讓助理尋找空氣品質監測站,並讀取全球污染物目前與歷史測量資料。
- 可以做什麼
- 依座標與半徑、邊界框或國家尋找監測站,可依污染物、監測站類型、移動性與提供者篩選,並列出各國涵蓋範圍及帶單位與參數 ID 的污染物目錄。讀取某測站各感測器的最新數值,並標示污染物與單位。取得某測站單一污染物的歷史序列,可選原始、按小時或按天彙總,並提示資料缺口與截斷。將大型序列暫存到 DataCanvas,以唯讀 SQL 檢視或查詢,並可選擇刪除暫存畫布。以資源形式讀取測站中繼資料與污染物目錄。
- 適用情境
- 適合讓助理回答特定地點或時段的實測空氣品質問題、比較監測站,或分析較長的污染物序列,而不必手寫 API 呼叫。它只提供實測感測器資料,不適合作為模型預測或一般天氣的來源。
- 執行需求
- 可使用公開託管的 Streamable HTTP 端點(免安裝),或透過 npm/npx、Bun 或 Docker 在本機執行;本機執行需 Bun v1.4.0+ 或 Node.js v24+。需要免費的 OpenAQ v3 API 金鑰,透過環境變數 OPENAQ_API_KEY 提供,並以 X-API-Key 標頭送出。DuckDB 畫布功能需設定 CANVAS_PROVIDER_TYPE=duckdb,且 .mcpb 套件不含此功能。需能存取 OpenAQ API 的網路。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Openaq Mcp Server,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。
交給代理程式安裝
把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。
閱讀 https://sourceweft.com/mcp/io.github.cyanheads%2Fopenaq-mcp-server/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。其他 MCP 客戶端
把它新增到你客戶端的 mcpServers 設定中。
{
"mcpServers": {
"openaq": {
"type": "http",
"url": "https://openaq.caseyjhand.com/mcp"
}
}
}README
@cyanheads/openaq-mcp-server
Find air-quality monitoring stations, read latest sensor values, and pull historical pollutant series via MCP. STDIO or Streamable HTTP.
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
coordinateswithradius(metres, 1–25000, default 12000),bbox, and/oriso(a code fromopenaq_list_countries); at least one is required, andcoordinatesandbboxexclude each other.parametersId,monitor,mobile, andprovidersIdnarrow further; up to 100 stations per page (limit, default 20), 1-basedpage - Each station carries
id,distanceMeters(coordinate search only),provider/providerId,isMonitor/isMobile, itsparameterswith units, and thedatetimeFirst/datetimeLastspan;coordinates,country, andproviderare null when OpenAQ lists none totalCountcounts stations through the current page and is a floor whentotalCountIsLowerBoundis set; no match fails asno_locations_found, a page past the end aspage_exhausted
openaq_get_readings tool
- A
locationId, orcoordinatesplusparametersIdto resolve the nearest station within 25 km that measures it (compared across up to 1,000 matching stations; a full 1,000 adds anotice); withlocationId,parametersIdoptionally filters to one parameter - One reading per sensor with
value,unit,sensorId, anddatetimeUtc/datetimeLocal, plus the station'sprovider,providerId,timezone, anddatetimeLast - Misses are typed:
location_not_found,parameter_not_at_location(with the station'savailableids),no_station_near_coordinates,no_recent_values
openaq_get_measurements tool
- Requires
locationIdandparametersId;datetimeFrom/datetimeToaccept UTC timestamps or station-localYYYY-MM-DDdates (UTC days when the station has no timezone).aggregationisraw(default),hourly, ordaily; up to 5,000 rows per call - Returns
series,sensorId,pulledCount,pullComplete,effectiveRange, and stationprovider,providerId, andtimezone.totalCountis a floor whentotalCountIsLowerBoundis set; rollups add summary statistics,gapCount, the first 20 missing intervals asgaps, and a notice when edge buckets are clipped - Past 100 rows,
seriesis a preview (truncated) and the pulled rows stage on a DataCanvas asmeasurements_<sensorId>(canvasId,tableName) whenCANVAS_PROVIDER_TYPE=duckdb; a suppliedcanvas_idstages 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
queryover code, display name, and description;pollutantsOnlydrops meteorological and particle-count channels - Rows carry
id,name,displayName,unit, anddescription; 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) andparametersId; up to 100 per page (limit, default 20), 1-basedpage - Rows carry
code(theisovalue foropenaq_find_locations),name, thedatetimeFirst/datetimeLastspan, and theparametersmeasured anywhere in the country;totalCountis the full filtered count
openaq_dataframe_describe tool
- Takes a
canvas_idfromopenaq_get_measurementsand returns each staged table'sname,rowCount, andcolumns. Call it beforeopenaq_dataframe_query: the staged table is flat (min,sd) while the inlineseriesnests those undersummary - Fails as
canvas_unavailableunlessCANVAS_PROVIDER_TYPE=duckdb, orcanvas_not_foundfor an unknown or expired id
openaq_dataframe_query tool
- A
canvas_idand one read-onlySELECT; writes, DDL, and file/network table functions are rejected - At most 200 rows per response, with
truncatedset when the cap cut the result; page withORDER BYplusLIMIT/OFFSET - Fails as
canvas_unavailable,canvas_not_found, ormissing_table
openaq_dataframe_drop tool
- Registered only with
OPENAQ_ENABLE_CANVAS_DROP=true; calls fail ascanvas_unavailableunlessCANVAS_PROVIDER_TYPE=duckdb. When disabled, the HTTP landing page shows the enable hint andtools/listomits the tool - Takes a
canvas_idand deletes that whole canvas, including all staged tables. Other agents sharing the id lose access; OpenAQ's source data is unaffected - Returns the requested
canvasIdanddropped: 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 withparameterIdandunit), and thedatetimeFirst/datetimeLastspanlocationIdcomes fromopenaq_find_locations; cached 5 minutes
openaq://parameters resource
application/jsoncatalog, the same rows as an unfilteredopenaq_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-Keyauth, 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_idcan be joined
Agent-friendly output:
- Measured, not modeled: a search with no station fails as
no_locations_foundorno_station_near_coordinates, stated as no coverage rather than clean air - Units travel with every value and are never converted;
parametersIdselects pollutant and unit together - Freshness and truncation are explicit: per-value timestamps and
datetimeLast, andtotalCount/truncated/noticeon 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:
Self-Hosted / Local
Add the following to your MCP client configuration file.
Or with npx (no Bun required):
Or with Docker:
Add "CANVAS_PROVIDER_TYPE": "duckdb" to env to enable DataCanvas SQL over large measurement series.
For Streamable HTTP, set the transport and start the server:
Prerequisites
- Bun v1.4.0 or higher (or Node.js v24+).
- A free OpenAQ v3 API key from an OpenAQ Explorer account.
Installation
- Clone the repository:
- Navigate into the directory:
- Install dependencies:
- Configure environment:
Configuration
See .env.example for the full list of optional overrides.
Running the server
Local development
-
Build and run:
-
Run checks and tests:
Docker
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/openaq-mcp-server. DuckDB 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
Development guide
See CLAUDE.md / AGENTS.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — catch only to map a failure to a declared error reason or to keep a partial result
- Use
ctx.logfor request-scoped logging,ctx.statefor 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
Contributing
Issues are welcome. Run checks and tests before submitting:
License
Apache-2.0 — see LICENSE for details.
Data comes from the OpenAQ platform, and attribution to OpenAQ is required when using this server's output (Terms of Use). OpenAQ aggregates measurements from government agencies, research institutions, and other networks, each of which may set its own attribution or licensing terms. The provider field on openaq_find_locations, openaq_get_readings, and openaq_get_measurements results and the openaq://location/{locationId} resource names the originating network; review and follow the terms of any provider whose data you use.
來源:README.md,提交 0b9e44a
工具
0版本歷史
5- v0.4.1最新Sep 27, 2026
- v0.3.0Sep 24, 2026
- v0.1.10Sep 22, 2026
- v0.1.9Sep 20, 2026
- v0.1.8Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通必需25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式必需10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分