# @cyanheads/nws-weather-mcp-server 中文文档

规范地址：https://npmcn.com/package/%40cyanheads/nws-weather-mcp-server/

版本：0\.12\.0
npm 元数据更新时间：2026-10-28T07:43:15.485Z
中文译文更新时间：2026-11-11T12:17:23.006Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cyanheads/nws-weather-mcp-server
原文对照：https://npmcn.com/package/%40cyanheads/nws-weather-mcp-server/?lang=original
项目主页：https://github.com/cyanheads/nws-weather-mcp-server#readme
源码仓库：https://github.com/cyanheads/nws-weather-mcp-server

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：625 kB，128 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：4 个
- 首次发布：2026-04-03T21:18:20.243Z
- 最新版本发布：2026-10-28T07:43:15.208Z
- 近 30 天下载量：2172（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

通过国家气象局API获取美国天气预报,主动警报和当前观测. (原始内容存档于2012-10-12). STIO or Streamable HTTP.

## 安装

```sh
npm install @cyanheads/nws-weather-mcp-server
```

也可以使用：`pnpm add @cyanheads/nws-weather-mcp-server`、`yarn add @cyanheads/nws-weather-mcp-server`、`bun add @cyanheads/nws-weather-mcp-server`

## README

# @cyanheads/nws-weather-mcp-server (英语)

**通过国家气象局API获取美国天气预报,主动警报和当前观测. (原始内容存档于2012-10-12). STIO or Streamable HTTP.**

10个工具 • 2个资源

[![Version](https://img.shields.io/badge/Version-0.12.0-blue.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/nws-weather-mcp-server/CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/nws-weather-mcp-server/LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/nws-weather-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-%5E2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/nws-weather-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/nws-weather-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-%5E7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/nws-weather-mcp-server/releases/latest/download/nws-weather-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=nws-weather-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbndzLXdlYXRoZXItbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22nws-weather-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fnws-weather-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

**公共主机服务器 :** [https://nws.caseyjhand.com/mcp 页面存档备份,存于互联网档案馆](https://nws.caseyjhand.com/mcp)

* * *

## 概览

美国国家气象局的实时天气:预报、主动警报、当前情况、50个州和美国领土任何地点的预报员讨论,加上区域预报、沿海和海洋警报,以及一周的台站历史。 不需要 API 密钥 .

### 工具

| 工具 | 说明 |
| :-- | :-- |
| `nws_get_forecast` | 坐标预报7天或小时。 内部决定核子系统网格. |
| `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://alert-types` | 所有有效的 NSS 提醒事件类型名称的静态列表 . |
| `skill://nws-weather-guide/SKILL.md` | 将预报、警报、站台趋势和预报员讨论结合起来的决定大门. |

警报类型也可通过 `nws_list_alert_types`。天气指南可通过 MCP 技能扩展和插件提供 `skills/` 目录.

## 能力参考

### `nws_get_forecast` 工具

-   `latitude` + 键 `longitude`; 默认返回14个命名的12小时周期(~7天),或与 `hourly: true` 有露点和湿度的一小时,上游为~156页,每页48个
-   `nextCursor` 搭载其模式,所以每小时步行一次继续每小时不续发 `hourly: true`
-   `include_amounts: true` 添加每个本地人 `quantitativePrecipitation`, (中文(简体) ), `snowfallAmount`,以及 `iceAccumulation` 间隔为 `precipitationAmounts` (单位:千美元)`layer`, (中文(简体) ), `uom`, (中文(简体) ), `values` 与 `validTime` 财务报告和审定财务报表 `value`),加上单独的 `amountsUpdateTime`。默认虚假;在任何需要金额的光标页面上重新发送。 中间字符串、单位、零和无值保持不变。 缺少的分层和无法提供的数额在以下表格中说明: `notice`; 现为空地层 `values: []`。缺勤单位或更新时间无效。 无法获取的量信息留下了主要预测.
-   回返 `updateTime`,当电网的预测数据最后一次更新时,除此之外 `generatedAt`页:1 `notice` 标记一个在24小时内未更新的网格
-   返回 `forecastZone` 财务报告和审定财务报表 `county` 连接到 `nws_search_alerts`
-   海洋坐标失败 `marine_forecast_unsupported`,而陆地点 NSS 则没有预测网格的故障 `no_forecast_grid`

* * *

### `nws_search_alerts` 工具

-   最多一个位置过滤器( E)`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`页:1 `point` 在无核子系统覆盖范围之外失败 `invalid_point`
-   每一个警报都携带着 `office` (为 `nws_get_office_discussion`,比如说. `RIW`),原样 `vtec` 字符串,该 `nwsHeadline`,以及 `hazard` 标记, 如 `maxHailSize` 财务报告和审定财务报表 `maxWindGust`逐字记录

* * *

### `nws_get_alert` 工具

-   `alert_id`: 警报 `id` 从 `nws_search_alerts`,或一个 `references[].identifier` 从任何提示;返回 `{ alert }` 形状与 `nws_search_alerts`,包括被替换的信息
-   一个错误的ID,一个未知的ID, 一个过去NWS的~7天的保留都失败了 `alert_not_found`

* * *

### `nws_get_alert_counts` 工具

-   无输入; 返回国家 `totalAlerts` (单位:千美元)`landAlerts` + 键 `marineAlerts`),加 (中文(简体) ) `areas` 按国家/领土或海洋区域代码和 `regions` 按海洋区域计数`AL`, (中文(简体) ), `AT`, (中文(简体) ), `GL`, (中文(简体) ), `GM`, (中文(简体) ), `PA`, (中文(简体) ), `PI`),每个代码只列出带有主动提醒的代码
-   计数涵盖每个消息状态,包括测试和练习,所以 `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 有秒和相抵的日期; 最新的第一, 通过 ~ 7 天 的 NWS 保存
-   `limit` (默认24)上限为100;较大的上限为100并报告通过 `requestedLimit`编号 :`effectiveLimit`
-   每个观察都带有 `nws_get_observations` 测量字段, `null` 站台没有报告;未知站台失效 `station_not_found`窗口或 `start` 之前没有 `end` 与 `invalid_time_window`
-   `nextCursor` 仅当旧的观测结果仍然存在时才会出现;没有 `totalCount`,因为核武器国家没有报告窗口

* * *

### `nws_find_stations` 工具

-   `latitude` + 键 `longitude`; 可选 `limit` (违约10)的上限为50;较大的上限为50,并通过 `requestedLimit`编号 :`effectiveLimit`
-   首先,每个结果都带有站名 `nws_get_observations`、相距(公里)、轴承、区码、高地和时区

* * *

### `nws_list_alert_types` 工具

-   返回 NWS API 所识别的全部事件类型( 如 “ Tornado 警告 ” 、 “ 热咨询 ” )
-   用于发现有效值 `event` 过滤器进入 `nws_search_alerts`

* * *

### `nws_get_office_discussion` 工具

-   `office`:通常3个字母的WFO代码(如"SEW"为西雅图所取)作为回取 `office` 字段为 `nws_get_forecast`· ; `product_type`数字 : `AFD` (违约), `HWO`, (中文(简体) ), `ZFP`, (中文(简体) ), `SPS`,或 `FWF` (火灾天气规划预报)
-   回返 `productText` 加号 `issuanceTime`, (中文(简体) ), `issuingOffice`, (中文(简体) ), `productName`, (中文(简体) ), `productCode`, (中文(简体) ), `wmoCollectiveId`· ; `content[]` 将产品文本带入 a `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` (单位:千美元) `code` 一、导 言 `affectedZones` 条目 `type: "forecast"`(中文(简体) )
-   以本地预测器的叙述文本返回命名的时段( 如“ 今天”、“ 今天晚上”、“ 星期一 ”)
-   县 (`XXC###`)和未知区域代码失败 `zone_not_found`,大多数消防区代码也一样, 其预测是FWF办公室的部分 `nws_get_office_discussion`; 火警代码也是公共区号返回公共区的预测; 没有文本预测的海洋区失败 `marine_forecast_unsupported`,和无 `zone_forecast_unavailable`

* * *

### `nws://alert-types` 资源

-   所有有效的 NSW 提醒事件类型名称的静态列表, 返回为 `application/json`
-   无参数; 公开缓存1小时

## 特征

建造在 [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio和可流式的 HTTP 传输器,可插接式(`none` 编号 : `jwt` 编号 : `oauth`),可互换存储(`in-memory`, (中文(简体) ), `filesystem`, (中文(简体) ), `Supabase`, (中文(简体) ), `Cloudflare KV/R2/D1`),结构化记录,可选择的OpenTeleometry tracking.

特定核武器国家:

-   发送所需 `User-Agent` 自动页眉( 可配置通过 `NWS_USER_AGENT`()——无核子系统返回403
-   自动坐标对网格分辨率通过 `/points`,缓存为 1h,因为网格单元格很少改变
-   请求超时加重试/ 后退, 用于瞬时的 NAWS API 失败
-   零自动访问——不需要 API 密钥
-   页面结果——通过返回 `nextCursor` 恢复为 `cursor` 用于下一页(在最后一页录入)

方便代理输出 :

-   证明——反应回放办公室代码,时区和区码,使特工可以连锁进入 `nws_get_office_discussion`, (中文(简体) ), `nws_get_zone_forecast`,以及 `nws_search_alerts`
-   对沉默的指导——空的、短的或光标后端的结果带有: `notice` 命名原因和下一步
-   输入出错的原因( E)`invalid_area_code`, (中文(简体) ), `no_products`, (中文(简体) ), `zone_not_found`,.)因此调用数据分支,而不是字符串解析
-   双单位计量(F/C、 mph/km/h、inHg/hPa、mi/km、in/mm),四舍五入,与文本输出相匹配

## 开始

连接到主机实例, 没有安装 :

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

或者在当地运行它:

```sh
claude mcp add nws-weather-mcp-server -- npx -y @cyanheads/nws-weather-mcp-server
```

对于其他客户端,请将此添加到 MCP 配置文件中 :

```json
{
  "mcpServers": {
    "nws-weather-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/nws-weather-mcp-server"]
    }
  }
}
```

`NWS_USER_AGENT` 可选择设置发送给核武器国家的联系人标识符。 对于 Docker 或源构建,请参见 [运行服务器](https://npmcn.com/package/%40cyanheads/nws-weather-mcp-server/#readme-running-the-server)。 。 。 .

## 配置

| 变量 | 说明 | 默认 |
| :-- | :-- | :-- |
| `NWS_USER_AGENT` | NWS API请求的用户代理. 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` |

见 [`.env.example`](https://npmcn.com/package/%40cyanheads/nws-weather-mcp-server/.env.example) 用于完整列表,包括认证、存储和OpenTeleometry选项.

## 运行服务器

### 地方发展

资源开发需要 [Bun v1.4 + 设备](https://bun.sh/)。已发布的可执行文件也运行在 [节点.js v24+](https://nodejs.org/)。 。 。 .

```sh
git clone https://github.com/cyanheads/nws-weather-mcp-server.git
cd nws-weather-mcp-server && bun install
cp .env.example .env
```

-   **构建并运行制作版本 :**
    
    ```sh
    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:http
    # or
    bun run start:stdio
    ```
    
-   **运行检查和测试 :**
    
    ```sh
    bun run devcheck     # Lints, formats, type-checks
    bun run test         # Runs test suite
    ```
    

### 夹克

```sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/nws-weather-mcp-server:latest
```

图像默认为 HTTP 传输、 无国籍会话模式和日志到 `/var/log/nws-weather-mcp-server`运行到一个 MCP 客户端的 stdio,使用 `"command": "docker"` 与 `"args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/nws-weather-mcp-server:latest"]`为了在当地建设, `docker build -t nws-weather-mcp-server .`; OpenTeleometry 等同器默认安装——用 `--build-arg OTEL_ENABLED=false` 以略去它们.

## 项目结构

| 目录 | 目的 |
| :-- | :-- |
| `src/index.ts` | `createApp()` 入场点——注册工具,警示型资源,并发布技能. |
| `skills/` | 出版的代理技能,也服务于MCP. |
| `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`](https://npmcn.com/package/%40cyanheads/nws-weather-mcp-server/CLAUDE.md) 发展准则和建筑规则。 简本:

-   搬运工投掷,框架渔获量——否 `try/catch` 在工具逻辑中
-   使用 `ctx.log` 用于特定域的伐木, `ctx.state` 用于存储
-   在枪管出口和出口中增加新的工具/资源 `createApp()` 数组在 `src/index.ts`
-   环绕 NSS API 调用: 验证原始 JSON → 规范域类型 → 返回输出计划; 永远不编织缺失的字段

## 捐款

问题值得欢迎。 提交前运行检查 :

```sh
bun run devcheck
bun run test
```

## 许可证

阿帕奇-2.0 — 见 [自由主义](https://npmcn.com/package/%40cyanheads/nws-weather-mcp-server/LICENSE) 详细情况.

## 常见问题

### @cyanheads/nws-weather-mcp-server 是什么？

通过国家气象局API获取美国天气预报,主动警报和当前观测\. \(原始内容存档于2012-10-12\)\. STIO or Streamable HTTP\.

### 如何安装 @cyanheads/nws-weather-mcp-server？

在项目目录运行 npm install @cyanheads/nws-weather-mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 nws-weather-mcp-server，可以用 npx nws-weather-mcp-server 直接运行。

### @cyanheads/nws-weather-mcp-server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cyanheads/nws-weather-mcp-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cyanheads/nws-weather-mcp-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cyanheads/nws-weather-mcp-server 可以商用吗？

@cyanheads/nws-weather-mcp-server 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cyanheads/nws-weather-mcp-server 的下载量有多少？

根据 npm 官方下载统计，@cyanheads/nws-weather-mcp-server 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,172 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cyanheads/nws-weather-mcp-server 还在维护吗？

最新版本 0\.12\.0 发布于 2026/10/28（14 天前）；至今共发布 41 个版本，其中过去 12 个月发布了 41 个；首次发布于 2026/04/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。