noaa-climate-mcp-server

---

概述

来自 NOAA 的历史天气和气候记录：Climate Data Online 的站点观测数据、Storm Events Database，以及 Billion-Dollar Weather and Climate Disasters 数据。查找站点、按所需单位获取观测数据，并查询风暴造成的损失或灾害成本。

工具

工具	描述
noaa_climate_list_datasets	列出可用的 CDO 数据集及其 ID、名称和时间覆盖范围
noaa_climate_list_data_categories	列出数据类别组（温度、降水、风等）
noaa_climate_list_data_types	按数据集或类别列出具体的测量标签（TMAX、TMIN、PRCP、SNOW 等）
noaa_climate_list_location_categories	列出用于限定位置搜索范围的 12 个位置类别
noaa_climate_find_locations	按类别搜索地理位置（州、城市、县、邮政编码、气候区），可选按名称筛选
noaa_climate_find_stations	按位置、边界框、数据集和数据类型搜索气象站
noaa_climate_get_station	按 ID 获取单个气象站的完整元数据
noaa_climate_fetch_data	获取指定数据集和日期范围的历史观测记录
noaa_climate_search_storm_events	在 NCEI Storm Events Database 中搜索某一年的事件——龙卷风、冰雹、洪水、飓风，以及损失、伤亡和叙述记录
noaa_climate_get_billion_dollar_disasters	查询 NOAA 已停用的 1980–2024 年 Billion-Dollar Weather and Climate Disasters 档案——每场灾害经 CPI 调整的损失和死亡人数，或按灾害类别统计的年度总数

资源

资源	描述
noaa://datasets	所有 CDO 数据集及其 ID 和时间覆盖范围——可注入上下文，在查询数据前帮助 Agent 做好准备
noaa://stations/{stationId}	按 ID 获取气象站元数据——名称、坐标、海拔和数据覆盖的日期范围

功能参考

noaa_climate_list_datasets _tool

• 无必需输入；可选按数据类型、位置、气象站和日期范围筛选；limit 为 1–1000（默认 25），可与 offset 搭配使用，并可按 id、name、mindate、maxdate 或 datacoverage 排序
• 返回每个数据集的 ID、名称和日期范围——GHCND（每日，1763 年至今）、GSOM（每月）、GSOY（每年）、NORMAL_DLY/MLY/ANN/HLY（1981–2010 年气候常态值）
• 日期筛选采用覆盖范围交集：对每个提供的边界，maxdate >= startDate 且 mindate <= endDate。筛选和分页前会先获取符合其他筛选条件的完整目录；总数反映筛选后的结果集。

---

noaa_climate_list_data_categories _tool

• 可选按数据集、位置、气象站和日期范围筛选；limit 为 1–1000（默认 25），可与 offset 搭配使用，并可按 id 或 name 排序
• 返回 42 个测量类别（温度、降水、风、气压、日照等），其 ID 可用作 datacategoryId，以缩小 noaa_climate_list_data_types 的查询范围

---

noaa_climate_list_data_types _tool

• 按 datasetId（例如 GHCND）或 datacategoryId（例如 TEMP）筛选；limit 为 1–1000（默认 25），可与 offset 搭配使用
• 返回 noaa_climate_fetch_data 可接受的数据类型 ID——常见的 GHCND 类型包括 TMAX、TMIN、PRCP、SNOW、SNWD、AWND——以及 CDO 提供的覆盖范围和日期范围

---

noaa_climate_list_location_categories _tool

• 仅支持分页和排序：limit 为 1–1000（默认 25），可与 offset 搭配使用，并可按 id 或 name 排序
• 返回 noaa_climate_find_locations 接受的 12 个类别 ID，作为 locationCategoryId 使用：CITY、ST、CNTY、CNTRY、ZIP、US_TERR、CLIM_REG、CLIM_DIV、HYD_ACC、HYD_CAT、HYD_REG、HYD_SUB

---

noaa_climate_find_locations _工具

• locationCategoryId 用于限定搜索范围（例如，ST 会返回全部 51 个州）；可选的 datasetId、datacategoryId 和日期范围筛选条件；limit 为 1–1000（默认 25），并支持 offset
• 返回 noaa_climate_find_stations 和 noaa_climate_fetch_data 所需的位置 ID — FIPS:37、CITY:US530018、ZIP:98101
• nameContains 可在一个最多包含 4,000 个位置的类别中按名称进行不区分大小写的匹配（除 ZIP 外的所有类别均适用）；未指定类别时会返回 name_filter_requires_category 错误，超过上限时会返回 name_filter_category_too_large 错误

---

noaa_climate_find_stations _工具

• 可按 locationId、extent（经纬度边界框）、datasetId、datatypeId（数组）和日期范围筛选；limit 为 1–1000（默认 25），并支持 offset
• extent 的格式为 minLat,minLon,maxLat,maxLon：四个有限的带符号十进制数或科学计数法数字，允许两侧有空格；纬度范围为 ±90， 经度范围为 ±180。坐标相同也有效；轴顺序颠倒时不会匹配任何结果，且参数会原样传递，不会跨越日期变更线环绕。
• 返回站点 ID（GHCND:USW00024233、COOP:010008）、名称、坐标、海拔和数据覆盖日期 — 这些 ID 可作为 stationId 传给 noaa_climate_fetch_data

---

noaa_climate_get_station _工具

• 唯一必需输入：stationId，取自 noaa_climate_find_stations；这是 noaa://stations/{stationId} 资源对应的工具形式
• 返回名称、坐标、海拔和完整的数据覆盖日期范围；格式正确的 ID 未解析到任何结果时会返回 not_found 错误

---

noaa_climate_fetch_data _工具

• 必须提供 datasetId、startDate、endDate；可选的 stationId、locationId、datatypeId 数组。GHCND、PRECIP_15、PRECIP_HLY、NORMAL_DLY、NORMAL_HLY、NEXRAD2 和 NEXRAD3 的时间跨度上限为 1 年；GSOM、GSOY、NORMAL_MLY 和 NORMAL_ANN 的上限为 10 年；任何 NORMAL_* 数据集都必须使用 startDate=2010-01-01 / endDate=2010-12-31
• 返回扁平的 { date, datatype, station, value, attributes } 记录，以及回显查询条件的 effectiveQuery；date_range_exceeded 会指出 CDO 接受的最晚日期 maxEndDate
• 强烈建议设置 units: "metric" 或 "standard" — 若不设置，GHCND 值将是原始的十分之一单位整数（例如，TMAX=256 表示 25.6°C）

---

noaa_climate_search_storm_events _工具

• 无需令牌；year 用于选择一个导出文件（1950 年至当前未结束的年份）；可按 episodeId（从返回事件中获取的精确数字字符串；会去除空格，空白值视为未设置，前导零仍有意义）、state（NCEI 全称，例如 "FLORIDA"）、eventType、month、startDate/endDate 和 minDamageInUsd 筛选；页数上限为 100（默认 50），并支持 offset
• 可选的 startDate/endDate 必须是有效的 YYYY-MM-DD 日期，并在损失核算、汇总和分页之前，根据事件日期跨度是否与日期范围重叠（含首尾日期）进行匹配。单边界、相同日期和跨年范围均有效；只有 year 用于选择导出文件。启用日期边界时，会排除源数据中缺失、无效或顺序颠倒的日期跨度；未设置边界时，这些行仍会显示。appliedDateRange 会在两种响应形式中回显所提供的边界。请求日期顺序颠倒时，会在下载前返回 invalid_date_range 错误。
• 每段不同的事件经过描述只会在 episodeNarratives 中出现一次，事件通过 episodeNarrativeRef 与其关联；每个事件的 eventNarrative 文本仍保留在对应事件中。渲染后的描述会保留原有标点和换行。可选的本地 ISO 格式 beginDate/endDate 值可用于 CDO 日期筛选，同时 NCEI 日期时间和时区字段保持不变。
• 损失金额会以带原始数量级后缀的字符串（"1.20M"）和解析后的美元金额返回；若 NCEI 未报告损失，则省略该字段，而不是将其置为零；未匹配到结果时，响应会列出该年份包含的事件类型和州
• 若 NCEI 未发布该年份的文件，则返回 year_unavailable 错误；下载的文件不符合预期表格格式时，则返回 malformed_export 错误

---

noaa_climate_get_billion_dollar_disasters _工具

• 默认返回单个灾害；设置 summary=true 可按灾害类别返回逐年计数和成本。可按 startYear/endYear、disasterType（七种 NCEI 类别之一）、minCostInUsd 和 state（两字母邮政编码）筛选；limit 为 1–100（默认 50），并可搭配 offset 使用
• 无论导出文件声明的单位是什么，所有成本都以整美元表示（并通过 declaredCostUnit 返回声明的单位）；指定 state 时，报告的是全国成本（costBasis: "national"）和按年份分档的 costRangeInUsd
• NOAA 已于 2024 年后停用该产品；1980–2024 年的存档仍可用，且不会再添加后续年份。coveredYears 会报告所选导出文件中实际包含的年份范围。每个成功响应都会附带此存档说明，以及任何限制调整或分页提示。
• 经 CPI 调整的成本保留存档导出文件中的调整值；服务不会将其重新换算为当前价格，也不会推断 CPI 基准年。

---

noaa://datasets _资源

• 所有 CDO 数据集，以 application/json 格式返回，包含 ID、名称和时间覆盖范围
• 等同于不带筛选条件且限制较高的 noaa_climate_list_datasets — 可注入上下文，无需获取数据

---

noaa://stations/{stationId} _资源

• stationId 来自 noaa_climate_find_stations；这是 noaa_climate_get_station 的资源形式
• 返回站点元数据；格式正确的 ID 未解析到任何站点时，将以 not_found 失败

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔认证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及带可选 OpenTelemetry 跟踪的结构化日志记录。

NOAA 专属功能：

• 完整覆盖 CDO API v2 — 数据集、数据类别、数据类型、地点、站点和观测数据 — 另提供两个无需令牌的独立 NCEI 批量 CSV 数据集：恶劣天气事件（Storm Events Database）和十亿美元级灾害成本
• 在调用 API 前，按数据集执行客户端日期范围验证，并向调用方报告确切的上游限制
• 发现工具会在发起任何请求前拒绝 startDate > endDate 的日期区间，返回 validation_error 并提示交换这两个值。日期相同或只提供一端的情况仍有效；紧凑格式 YYYYMMDD、不补零的连字符日期，以及受支持的精确到秒的日期时间格式，都会先规范化再进行比较。
• 通过 CDO 的 units 参数规范化单位，避免将原始的十分之一单位整数误认为实际单位
• 提取并返回 CDO 自身的拒绝消息 — 日期范围过长、日期格式错误或缺少参数时，会报告 CDO 给出的原因，而不是只返回一行状态信息
• 十亿美元级灾害成本会根据每份 NCEI 导出文件前言中声明的单位转换为整美元，因为不同导出文件使用的单位可能不同

面向 Agent 的输出：

• 所有列表和搜索工具均支持分页 — 输入和返回的元数据中，offset 均从零开始。经过本地筛选的数据集和地点视图会根据筛选结果生成元数据；其他 CDO 分页会保留上游缺失的元数据。坐标和覆盖范围保留上游精度；覆盖范围文本使用原始小数，并标记为 0–1。
• 正整数读取限制会被钳制到页面上限：CDO 为 1000，Storm Events 和十亿美元级灾害为 100。通知会在提供空页或结果耗尽提示的同时，列出请求的限制和实际应用的限制；前进时请使用实际应用的限制来更新 offset。每次钳制都会记录日志，并计入 noaa.pagination.limit_clamped。
• 站点、地点和数据集 ID 可在工具间顺畅传递 — 查找地点、查找其中的站点，再获取这些站点的数据
• 提供带类型化 reason 代码和恢复提示的结构化错误契约 — Agent 可根据数据分支处理，无需解析字符串
• 损失和成本字段如实反映上游数据缺漏 — 未报告的 NCEI 数值会被省略，而不会被当作已确认的零值

入门

公共托管实例

可使用公共实例：https://noaa-climate.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "noaa-climate-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/noaa-climate-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NOAA_CDO_TOKEN": "your-token-here"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "noaa-climate-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/noaa-climate-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NOAA_CDO_TOKEN": "your-token-here"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "noaa-climate-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "NOAA_CDO_TOKEN=your-token-here", "ghcr.io/cyanheads/noaa-climate-mcp-server:latest"]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NOAA_CDO_TOKEN=your-token-here bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js ≥24.0.0）。
• 免费的 NOAA CDO API 令牌 — CDO 请求需要此令牌；Storm Events 和 Billion-Dollar Disasters 无需令牌。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/noaa-climate-mcp-server.git

2. 进入目录：

cd noaa-climate-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set required vars

配置

服务专属配置使用 src/config/server-config.ts 中的 Zod schema。页数上限策略会在启动时验证；运行 CDO 请求时需要 CDO 令牌。主要环境变量：

变量	描述	默认值
NOAA_CDO_TOKEN	CDO 必需。 可在 ncdc.noaa.gov/cdo-web/token 免费获取；两个批量语料库无需令牌	—
NOAA_CLAMP_LIMITS	true 会将正整数读取限制值钳制到页数上限；false 则恢复超过上限时由 schema 拒绝。只接受精确字符串 true 和 false；其他非空值会导致启动失败。更改此设置后需重启。	true
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_ENDPOINT_PATH	MCP 服务挂载的 HTTP 端点路径	/mcp
MCP_SESSION_MODE	HTTP 会话模式：stateful、stateless 或 auto。默认使用 stateless — 没有工具会在处理程序中途要求调用方输入	stateless
MCP_PUBLIC_URL	用于 TLS 终止反向代理部署的公共源地址覆盖值	无
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）	info
MCP_GC_PRESSURE_INTERVAL_MS	可选的、仅限 Bun 的强制 GC 压力循环（毫秒）。如果持续 HTTP 负载下观察到堆增长，可尝试设置为 60000。	0（已禁用）
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	启用 OpenTelemetry	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 基础 URL；跟踪数据发送到 /v1/traces，指标发送到 /v1/metrics。未设置此项时不会导出任何数据	无
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用的参数和结果，按键名脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认 16384）字节。自由格式值中的机密不会被脱敏。	false

完整的可选覆盖项列表请参见 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  bun run test:live # Opt-in: resolves every documented example identifier against the live CDO API
  

Docker

docker build -t noaa-climate-mcp-server .
docker run --rm -e NOAA_CDO_TOKEN=your-token-here -p 3010:3010 noaa-climate-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/noaa-climate-mcp-server。默认会安装 OpenTelemetry 对等依赖项 — 构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/mcp-server/tools	工具定义（*.tool.ts）。涵盖数据集、地点、站点、观测、风暴事件和灾害成本的十个工具。
src/mcp-server/resources	资源定义。数据集目录和站点元数据资源。
src/services/cdo	CDO HTTP 客户端，支持重试、退避、camelCase→小写参数转换，以及恢复 CDO 自身的拒绝消息。
src/services/csv	增量式 RFC 4180 CSV 读取器，由两个 NCEI 批量 CSV 数据集共用。
src/services/storm-events	NCEI 风暴事件批量 CSV 客户端——文件名发现、流式解压和损失解析。
src/services/billion-dollar-disasters	NCEI 十亿美元灾害客户端——声明单位解析，并转换为整美元。
src/config	使用 Zod 解析并验证服务专属环境变量。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明如下：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 createApp() 数组中注册新工具和资源
• 将外部 API 调用封装为：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。