
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 分