nws-weather-mcp-server

---

概述

来自国家气象局的美国实时天气信息：覆盖 50 个州和美国属地任意地点的天气预报、正在生效的预警、当前状况和预报员讨论内容，此外还包括区域预报、沿海和海洋预警，以及一周的气象站历史记录。无需 API 密钥。

工具

工具	描述
nws_get_forecast	按坐标提供 7 天或逐小时天气预报。内部解析 NWS 网格。
nws_search_alerts	按区域、地点、分区、事件、严重程度、紧迫性、确定性和状态筛选正在生效的天气预警。
nws_get_alert	按 ID 获取一条预警消息，可以是当前预警或已被取代的预警（保留约 7 天）。
nws_get_alert_counts	获取全国、各州/属地或海洋区域，以及各海洋分区的生效预警数量。
nws_get_observations	按坐标（最近的气象站）或气象站 ID 获取当前状况。
nws_get_observation_history	获取气象站最近的观测数据，按时间从新到旧排列；可分页查看 NWS 保留的约 7 天数据。
nws_find_stations	查找附近的观测气象站，按距离排序并显示方位。
nws_list_alert_types	列出所有有效的预警事件类型名称，以便发现可用筛选项。
nws_get_office_discussion	获取气象预报办公室发布的最新叙述性产品（AFD、HWO、ZFP、SPS、FWF）；如果产品太大而无法内联返回，则会返回章节大纲。
nws_get_zone_forecast	获取 NWS 预报分区的文字预报时段。

资源

资源	描述
nws://alert-types	所有有效 NWS 警报事件类型名称的静态列表。

也可通过 nws_list_alert_types 工具访问，适用于不支持资源的 MCP 客户端。

功能参考

nws_get_forecast _工具

• latitude + longitude；默认返回 14 个命名的 12 小时时段（约 7 天），或设置 hourly: true 后返回逐小时时段，包含露点和湿度；上游约 156 个时段，每页 48 个
• nextCursor 会携带其模式，因此按小时遍历时无需重新发送 hourly: true，后续页面会继续按小时返回
• include_amounts: true 会将每个原生 quantitativePrecipitation、snowfallAmount 和 iceAccumulation 时段作为 precipitationAmounts（包含 layer、uom、带有 validTime 和 value 的 values）添加，并另行提供 amountsUpdateTime。默认为 false；任何需要降水量的游标页面都需重新发送此参数。时段字符串、单位、零值和 null 值均保持不变。缺失的图层和不可用的降水量会在 notice 中说明；存在但为空的图层会包含 values: []。缺失的单位或更新时间为 null。降水量数据源不可用时，主要预报仍可用。
• 返回 updateTime（网格预报数据的最近更新时间），与 generatedAt 并列；若网格超过 24 小时未更新，则会通过 notice 发出提示
• 返回 forecastZone 和 county 区域代码，可用于后续调用 nws_search_alerts
• 海洋坐标会因 marine_forecast_unsupported 失败；NWS 未提供预报网格的陆地点会因 no_forecast_grid 失败

---

nws_search_alerts _工具

• 最多指定一个位置筛选条件（area、point、zone、region_type 或 region），也可不指定以进行全国搜索；event 不区分大小写并支持部分匹配；status 默认为 Actual（也可为 Exercise、System、Test、Draft）
• limit（默认为 25）上限为 25；若指定更大的值，则按 25 条返回，并通过 requestedLimit/effectiveLimit 报告
• nextCursor 会携带查询筛选条件和每页大小，因此只需将其作为 cursor 传回；随其发送的筛选条件会被忽略
• 每个 affectedZones 条目都包含其区域 type（forecast/county/fire）；references 按 sent 从新到旧列出已被取代的消息；NWS 覆盖范围外的 point 会因 invalid_point 失败
• 每条警报都包含 office（签发办公室代码，可用于调用 nws_get_office_discussion，例如 RIW）、原始 vtec 字符串、nwsHeadline，以及 maxHailSize 和 maxWindGust 等 hazard 标签，内容原样保留

---

nws_get_alert _工具

• alert_id：来自 nws_search_alerts 的警报 id，或任意警报中 references[].identifier 的值；返回与 nws_search_alerts 结构相同的 { alert }，包括已被取代的消息
• 格式错误的 ID、未知 ID，以及超出 NWS 约 7 天保留期限的 ID 均会因 alert_not_found 失败

---

nws_get_alert_counts _工具

• 无输入；返回全国 totalAlerts（landAlerts + marineAlerts），以及按州/地区或海洋区域代码统计的 areas 数量和按海洋区域统计的 regions 数量（AL、AT、GL、GM、PA、PI）；两者都只列出存在有效警报的代码
• 统计涵盖所有消息状态，包括 Test 和 Exercise，因此 totalAlerts 可能高于全国 nws_search_alerts 的 totalCount（status: Actual 为默认值）；每条警报会在其所属的每个区域各计一次，因此 areas 的总和可能超过 totalAlerts

---

nws_get_observations _工具

• 可按坐标查询（解析到最近的站点），也可直接使用 station_id
• 每项测量都以双单位显示（F/C、mph/km/h、inHg/hPa、mi/km、in/mm），温度精确到小数点后一位；根据每小时报告提供 1 小时、3 小时和 6 小时降水量，其中 0 表示微量，null 表示未报告降水量；超过 2 小时的观测会附带过时提示，另有单独警告标记大多数测量数据不可用的站点

nws_get_observation_history _工具

• station_id（来自 nws_find_stations）；可选的 start（包含）和 end（不包含）为 ISO 8601 日期时间，精确到秒并带有偏移量；结果按时间从新到旧排列，最早可追溯到 NWS 保留的约 7 天数据
• limit（默认值为 24）上限为 100；若设置更大的值，则按 100 返回，并通过 requestedLimit/effectiveLimit 报告
• 每条观测都包含 nws_get_observations 的测量字段；若站点未报告某项数据，则该字段为 null；未知站点会返回 station_not_found 错误，时间窗口格式错误或 start 不早于 end 时会返回 invalid_time_window 错误
• 仅当还有更早的观测时才会出现 nextCursor；由于 NWS 不会提供窗口的总数，因此没有 totalCount

---

nws_find_stations _工具

• latitude + longitude；可选的 limit（默认值为 10）上限为 50；若设置更大的值，则按 50 返回，并通过 requestedLimit/effectiveLimit 报告
• 按距离从近到远排列；每条结果都包含用于 nws_get_observations 的站点 ID、距离（km）、方位、区域代码、海拔和时区

---

nws_list_alert_types _工具

• 返回 NWS API 识别的所有事件类型（例如，“Tornado Warning”“Heat Advisory”）
• 用于查找 nws_search_alerts 中 event 过滤条件的有效值

---

nws_get_office_discussion _工具

• office：通常为 3 个字母的 WFO 代码（例如西雅图对应的 “SEW”），由 nws_get_forecast 作为 office 字段返回；product_type：AFD（默认值）、HWO、ZFP、SPS 或 FWF（Fire Weather Planning Forecast）
• 返回 productText，以及 issuanceTime、issuingOffice、productName、productCode、wmoCollectiveId；content[] 会在 text 代码块中提供产品文本，以保留定宽表格的列布局；未知办公室，或没有所请求类型当前产品的办公室，会返回 no_products 错误
• 产品过大，无法以内联方式返回（大多数 ZFP 和 FWF）时，会返回各部分的 outline，而不是 productText；传入 sections（AFD 部分名称，或 ZFP/HWO/SPS/FWF 的区域代码）以获取对应部分；未知名称会返回 unknown_section 错误
• 类型为 fire 的预警区域，其预报来自 FWF：使用预警的 office 字段作为 office，设置 product_type: "FWF"，并设置 sections: [<zone code>]

---

nws_get_zone_forecast _工具

• zone_id：预报区域代码（例如，“WAZ315”）——由 nws_get_forecast（forecastZone）、nws_find_stations（forecastZone 列）和 nws_search_alerts（affectedZones 条目中 type: "forecast" 的 code）返回
• 返回各时段的名称（例如，“Today”“Tonight”“Monday”）以及当地预报员撰写的文字说明
• 县代码（XXC###）和未知区域代码会返回 zone_not_found 错误；大多数火灾区域代码也会返回此错误，因为其预报来自 nws_get_office_discussion 中该办公室 FWF 对应的部分；同时也是公共区域代码的火灾代码会返回公共区域的预报；没有文字预报的海洋区域会返回 marine_forecast_unsupported 错误，没有文字预报的陆地区域会返回 zone_forecast_unavailable 错误

---

nws://alert-types _资源

• 包含所有有效 NWS 预警事件类型名称的静态列表，以 application/json 格式返回
• 无参数；公开缓存 1 小时

功能特性

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

NWS 专属功能：

• 自动发送必需的 User-Agent 标头（可通过 NWS_USER_AGENT 配置）——没有该标头时，NWS 会返回 403
• 通过 /points 自动将坐标解析为网格，并缓存 1 小时，因为网格单元很少变化
• 针对 NWS API 的暂时性故障设置请求超时并进行重试和退避
• 无需身份验证——不需要 API 密钥
• 分页结果——将返回的 nextCursor 作为 cursor 传入以获取下一页（最后一页会省略该字段）

便于 Agent 使用的输出：

• 来源信息——响应会回显办事处代码、时区和区域代码，便于 Agent 接续调用 nws_get_office_discussion、nws_get_zone_forecast 和 nws_search_alerts
• 提供指引，而非沉默——结果为空、被截断或游标超出末尾时，会附带说明原因和后续步骤的 notice
• 提供类型化错误原因（invalid_area_code、no_products、zone_not_found，……），让调用方根据数据分支，而不必解析字符串
• 双单位测量值（F/C、mph/km/h、inHg/hPa、mi/km、in/mm），并进行四舍五入以匹配文本输出

开始使用

公共托管实例

可通过 https://nws.caseyjhand.com/mcp 使用公共实例——无需安装。该实例提供 Streamable HTTP；每个客户端的配置格式各不相同。

Claude Code 配置：

claude mcp add --transport http nws-weather-mcp-server https://nws.caseyjhand.com/mcp

Cline 配置（cline_mcp_settings.json）：

{
  "mcpServers": {
    "nws-weather-mcp-server": {
      "type": "streamableHttp",
      "url": "https://nws.caseyjhand.com/mcp"
    }
  }
}

Cursor 配置（mcp.json）：

{
  "mcpServers": {
    "nws-weather-mcp-server": {
      "url": "https://nws.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在“设置”→“连接器”下添加远程服务。

自托管 / 本地部署

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

{
  "mcpServers": {
    "nws-weather-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/nws-weather-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "nws-weather-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/nws-weather-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "nws-weather-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/nws-weather-mcp-server:latest"]
    }
  }
}

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

MCP_TRANSPORT_TYPE=http MCP_SESSION_MODE=stateless MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Node.js v24+ 或 Bun v1.4+

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/nws-weather-mcp-server.git

2. 进入目录：

cd nws-weather-mcp-server

3. 安装依赖：

bun install

配置

变量	描述	默认值
NWS_USER_AGENT	NWS API 请求使用的 User-Agent。API 要求提供此标头。	(nws-weather-mcp-server, ...)
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_HOST	HTTP 服务的主机名。	127.0.0.1
MCP_SESSION_MODE	HTTP 会话模式：stateful、stateless 或 auto。	stateless
MCP_LOG_LEVEL	日志级别：debug、info、notice、warning、error。	info

完整列表（包括身份验证、存储和 OpenTelemetry 选项）请参阅 .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
  bun run test         # Runs test suite
  

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源。
src/mcp-server/tools/definitions/	工具定义（*.tool.ts）。
src/mcp-server/resources/definitions/	资源定义（*.resource.ts）。
src/services/nws/	NWS API 客户端和响应类型。
src/config/	使用 Zod 解析并验证环境变量。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

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

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录领域特定日志，使用 ctx.state 进行存储
• 将新工具/资源添加到 barrel 导出，以及 src/index.ts 中的 createApp() 数组
• 封装 NWS API 调用：验证原始 JSON → 规范化为领域类型 → 返回输出模式；绝不捏造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。