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.

已验证Streamable HTTP可网页运行位置与生活数据与分析

概览

AI 生成的概览

一个 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 的网络。
安装前请注意
OpenAQ API 密钥是机密,经 OPENAQ_API_KEY 传入,勿放入共享配置。画布删除工具会删除整个暂存画布,默认关闭,需设置 OPENAQ_ENABLE_CANVAS_DROP=true;关闭认证时调用方共享同一租户,任何持有画布 ID 的人都能删除它。启用 LOG_TOOL_FAILURE_PAYLOADS 会记录失败调用的参数和结果,仅按键名脱敏。查询内容和站点坐标会发送到 OpenAQ API。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Openaq Mcp Server,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

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.

8 Tools (7 enabled by default) • 2 Resources

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

ToolDescription
openaq_find_locationsFind monitoring stations near a point, in a bounding box, or by country; the location ids the other tools take
openaq_get_readingsLatest value for every sensor at a station, labeled with its pollutant and unit
openaq_get_measurementsHistorical series for one pollutant at one station, raw or rolled up hourly/daily
openaq_list_parametersPollutant catalog with canonical units; maps a pollutant and unit to its parameter id
openaq_list_countriesCountry coverage: data span and the parameters measured in each
openaq_dataframe_describeList the tables and columns staged on a DataCanvas
openaq_dataframe_queryRun a read-only SQL SELECT over staged measurement series
openaq_dataframe_dropDelete a complete staged canvas; opt-in with OPENAQ_ENABLE_CANVAS_DROP=true

Resources

ResourceDescription
openaq://location/{locationId}Metadata for one station: coordinates, provider, sensors with units, data span
openaq://parametersFull pollutant and unit catalog

Both resources mirror tool output, so tool-only clients lose nothing.

Capability reference

openaq_find_locations tool

  • Scope by coordinates with radius (metres, 1–25000, default 12000), bbox, and/or iso (a code from openaq_list_countries); at least one is required, and coordinates and bbox exclude each other. parametersId, monitor, mobile, and providersId narrow further; up to 100 stations per page (limit, default 20), 1-based page
  • Each station carries id, distanceMeters (coordinate search only), provider/providerId, isMonitor/isMobile, its parameters with units, and the datetimeFirst/datetimeLast span; coordinates, country, and provider are null when OpenAQ lists none
  • totalCount counts stations through the current page and is a floor when totalCountIsLowerBound is set; no match fails as no_locations_found, a page past the end as page_exhausted

openaq_get_readings tool

  • A locationId, or coordinates plus parametersId to resolve the nearest station within 25 km that measures it (compared across up to 1,000 matching stations; a full 1,000 adds a notice); with locationId, parametersId optionally filters to one parameter
  • One reading per sensor with value, unit, sensorId, and datetimeUtc/datetimeLocal, plus the station's provider, providerId, timezone, and datetimeLast
  • Misses are typed: location_not_found, parameter_not_at_location (with the station's available ids), no_station_near_coordinates, no_recent_values

openaq_get_measurements tool

  • Requires locationId and parametersId; datetimeFrom/datetimeTo accept UTC timestamps or station-local YYYY-MM-DD dates (UTC days when the station has no timezone). aggregation is raw (default), hourly, or daily; up to 5,000 rows per call
  • Returns series, sensorId, pulledCount, pullComplete, effectiveRange, and station provider, providerId, and timezone. totalCount is a floor when totalCountIsLowerBound is set; rollups add summary statistics, gapCount, the first 20 missing intervals as gaps, and a notice when edge buckets are clipped
  • Past 100 rows, series is a preview (truncated) and the pulled rows stage on a DataCanvas as measurements_<sensorId> (canvasId, tableName) when CANVAS_PROVIDER_TYPE=duckdb; a supplied canvas_id stages 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 query over code, display name, and description; pollutantsOnly drops meteorological and particle-count channels
  • Rows carry id, name, displayName, unit, and description; 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) and parametersId; up to 100 per page (limit, default 20), 1-based page
  • Rows carry code (the iso value for openaq_find_locations), name, the datetimeFirst/datetimeLast span, and the parameters measured anywhere in the country; totalCount is the full filtered count

openaq_dataframe_describe tool

  • Takes a canvas_id from openaq_get_measurements and returns each staged table's name, rowCount, and columns. Call it before openaq_dataframe_query: the staged table is flat (min, sd) while the inline series nests those under summary
  • Fails as canvas_unavailable unless CANVAS_PROVIDER_TYPE=duckdb, or canvas_not_found for an unknown or expired id

openaq_dataframe_query tool

  • A canvas_id and one read-only SELECT; writes, DDL, and file/network table functions are rejected
  • At most 200 rows per response, with truncated set when the cap cut the result; page with ORDER BY plus LIMIT/OFFSET
  • Fails as canvas_unavailable, canvas_not_found, or missing_table

openaq_dataframe_drop tool

  • Registered only with OPENAQ_ENABLE_CANVAS_DROP=true; calls fail as canvas_unavailable unless CANVAS_PROVIDER_TYPE=duckdb. When disabled, the HTTP landing page shows the enable hint and tools/list omits the tool
  • Takes a canvas_id and deletes that whole canvas, including all staged tables. Other agents sharing the id lose access; OpenAQ's source data is unaffected
  • Returns the requested canvasId and dropped: 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 with parameterId and unit), and the datetimeFirst/datetimeLast span
  • locationId comes from openaq_find_locations; cached 5 minutes

openaq://parameters resource

  • application/json catalog, the same rows as an unfiltered openaq_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-Key auth, 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_id can be joined

Agent-friendly output:

  • Measured, not modeled: a search with no station fails as no_locations_found or no_station_near_coordinates, stated as no coverage rather than clean air
  • Units travel with every value and are never converted; parametersId selects pollutant and unit together
  • Freshness and truncation are explicit: per-value timestamps and datetimeLast, and totalCount / truncated / notice on 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:

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

Self-Hosted / Local

Add the following to your MCP client configuration file.

json
{  "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):

json
{  "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:

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

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:

sh
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

Installation

  1. Clone the repository:
sh
git clone https://github.com/cyanheads/openaq-mcp-server.git
  1. Navigate into the directory:
sh
cd openaq-mcp-server
  1. Install dependencies:
sh
bun install
  1. Configure environment:
sh
cp .env.example .env# edit .env and set OPENAQ_API_KEY

Configuration

VariableDescriptionDefault
OPENAQ_API_KEYRequired. OpenAQ v3 API key, sent as the X-API-Key header.—
OPENAQ_API_BASE_URLOpenAQ v3 API base URL, for a proxy or test mirror.https://api.openaq.org/v3
CANVAS_PROVIDER_TYPEduckdb stages large measurement series for SQL via the dataframe tools; without it, large series return a preview plus a notice. The .mcpb bundle ships without DuckDB, so use npm, npx, or Docker for canvas work.none
OPENAQ_ENABLE_CANVAS_DROPEnable openaq_dataframe_drop to delete entire canvases and release their resources. Requires DuckDB; an id shared with another agent grants deletion access within the same tenant.false
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTHTTP server port.3010
MCP_SESSION_MODEHTTP session mode: stateless, stateful, or auto. Overrides the server's explicit stateless posture; auto resolves to stateful.stateless
MCP_AUTH_MODEAuthentication: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.).info
OTEL_ENABLEDEnable OpenTelemetry.false
OTEL_EXPORTER_OTLP_ENDPOINTOTLP base URL; traces use /v1/traces and metrics use /v1/metrics. Signal-specific endpoints override it.—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOpt into OTLP log export with a full endpoint URL. The base endpoint never enables logs.—
LOG_TOOL_FAILURE_PAYLOADSLog failed calls' arguments and results. Redacts by key name only; secrets in free-form values remain.false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTESUTF-8 byte cap per logged failure payload.16384

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

Running the server

Local development

  • Build and run:

    sh
    bun run rebuildbun run start:http   # or start:stdio
  • Run checks and tests:

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

Docker

sh
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. 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

DirectoryPurpose
src/index.tscreateApp() entry point: registers tools and resources, wires the service and canvas.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (definitions/*.tool.ts) and shared input, error, and format helpers (shared/).
src/mcp-server/resourcesResource definitions (definitions/*.resource.ts).
src/servicesOpenAQ v3 client and domain types (openaq/), plus the DataCanvas accessor.
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 — catch only to map a failure to a declared error reason or to keep a partial result
  • 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

Contributing

Issues are welcome. Run checks and tests before submitting:

sh
bun run devcheckbun run test

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
SourceWeft 尚未读取此服务器的工具。

版本历史

5
  1. v0.4.1最新Sep 27, 2026
  2. v0.3.0Sep 24, 2026
  3. v0.1.10Sep 22, 2026
  4. v0.1.9Sep 20, 2026
  5. v0.1.8Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式必需10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分