Weather

MCP Weather Server — 面向 AI Agent 的美国警报和预报

一个精简的模型上下文协议服务，通过两个只读工具提供来自美国国家气象局 API的美国天气数据。

NWS API 免费、无需密钥且仅限美国，因此此服务无需凭据或账户即可运行。

工具	输入	返回内容
get-alerts	state — 两个字母的代码，例如 CA	该州的有效天气警报
get-forecast	latitude、longitude	该坐标点接下来的五个预报时段

两个工具均标注为 readOnlyHint: true 和 destructiveHint: false，因此遵循工具注释的宿主可以直接调用，无需事先询问。两个工具都会访问 api.weather.gov，因此均标记为 openWorldHint: true。

托管使用，按次付费

自行运行无需费用。此外，还有托管版本，通过 x402 在 Base 上以 USDC 按次付费，适合不想运行 Node 进程和数据层的 Agent：

https://agent-evidence.thx93.dev/weather/mcp

它提供相同的两个工具，使用相同的输出架构和相同的 null 回退值，另外还提供免费的 health 工具和免费的 tools/list，以便在付费前发现和探测服务。发现免费；调用 get-alerts 或 get-forecast 的 tools/call 请求会返回带有价格的 402 响应。两个工具均声明为只读，因此遵循注释的宿主不会重复询问。

此仓库中的 server.json 会公布该远程服务，因此 MCP 客户端可以按注册表名称安装，而无需克隆任何内容。

先决条件

• Node.js 24+
• npm

构建、测试和运行

npm install
npm test          # builds, then runs the suite
npm run build     # compile only
node build/index.js

测试套件通过 InMemoryTransport 驱动真实服务，并使用 NWS API 存根，因此 npm test 不会访问网络，也不需要凭据。测试涵盖工具发现和注释、get-alerts 和 get-forecast 数据路径、NWS 将字段发送为 null 时的回退值、失败约定以及输入验证。

运行 node build/index.js 会通过 stdio 使用 MCP 协议：它会向 stderr 输出内容，并等待 stdin 上的客户端，因此此命令是供宿主启动的，不适合手动运行。

添加到客户端

大多数 MCP 宿主都使用相同的三行格式：

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-weather-server/build/index.js"]
    }
  }
}

也可以直接从 npm 获取 — 发布于 2026-10-19：

npx -y @thx93/mcp-weather-server

或者，作为客户端配置条目：

{
  "mcpServers": {
    "weather": { "command": "npx", "args": ["-y", "@thx93/mcp-weather-server"] }
  }
}

也可以直接从仓库获取，无需注册表账户：

npm install github:Thx93/mcp-weather-server

这种方式可行，是因为 prepare 会在安装期间构建服务；build/ 不会提交，因此如果没有这一步，bin 就会指向一个不存在的文件。此方式已通过端到端验证 — 从 GitHub 安装，然后与结果进行 MCP 通信，两个工具均会列出并带有对象输出架构。

对照源数据验证

这些工具返回的是美国国家气象局自己的数据，因此正确性可以核验，而非仅凭断言。2026-10-19，api.weather.gov 报告 TX 有一条有效警报，且对托管版 get-alerts 的一次付费调用针对同一州准确返回了一条警报 — Event: Flood Advisory。

这比听起来更重要：相关的证据服务在其判定中存在有记录的可靠性缺口（参见其 docs/evidence-quality.md），而这些工具不会做出可能出错的推断判断。它们只负责获取并重整数据；这些值来自 NWS。

值得了解的行为

失败会作为工具结果返回，而不是协议错误。 NWS 无法响应的请求—— 非美国境内的位置、服务中断、超时——会返回 { isError: true, content: [{ type: "text", text: "<what failed>" }] }。这就是 MCP 对“调用格式正确，但执行失败”的约定，与 JSON-RPC 错误不同；后者表示调用本身有问题。客户端可以向用户显示这段文本，并重试。

NWS 慢悠悠地放弃，而我们不会。 每个请求都有 10 秒超时，因此上游服务卡住时，会表现为工具调用失败，而不是一直挂起。

缺失字段会使用备用值，而不是输出 null。 NWS 对不存在的字段会返回 null。缺失的事件名称会显示为 Unknown，缺失的温度也会显示为 Unknown——绝不会显示字面字符串 null。

get-forecast 最多返回五个时段。 足以回答“天气怎么样”，长度也适合放入上下文窗口。

结构化内容

两个工具都声明了 outputSchema 并返回 structuredContent，且两个架构都是对象：get-forecast 返回 { latitude, longitude, periods }，get-alerts 返回 { alerts: [...] }。

get-alerts 之前声明了顶层数组，而协议修订版 2026-07-28 确实允许这样做。后来进行了修改，因为使用广泛部署的 MCP SDK 的客户端遇到数组架构时，会拒绝整个 tools/list 响应—— invalid_value: expected "object"——导致这类客户端完全无法连接到服务。 将数组包装在对象中，才能让普通客户端访问这些工具；模型读取的文本摘要则保持不变。

常见问题

这是什么？ 这是一个 MCP（Model Context Protocol）服务，将美国国家气象局的美国天气数据作为两个只读工具 get-alerts 和 get-forecast 提供。安装后通过 stdio 运行，同一份代码也通过可流式传输的 HTTP 在 https://agent-evidence.thx93.dev/weather/mcp 上提供服务，按调用次数收费。

我需要 API 密钥吗？ 不需要。美国国家气象局 API 不需要密钥，本地服务和托管端点也都不需要密钥、账户或注册。

费用是多少？ 自行运行免费——它采用 ISC 许可证，并以 @thx93/mcp-weather-server 发布在 npm 上。托管端点通过 x402 在 Base 上按次收费，每次调用 0.01 USDC；这样一来，拥有钱包但无法注册账户的 Agent 仍可调用它。

支持哪些地点？ 仅限美国。数据来自美国国家气象局，其覆盖范围包括美国及其领土。超出覆盖范围的坐标会返回错误，而不是猜测结果。

这些工具会返回什么？ get-alerts 接受两位字母的州代码，并返回所有有效警报：事件、区域、严重程度、描述和官方指示。get-forecast 接受纬度和经度，并返回五个天气预报时段：名称、温度、风速和风向，以及通俗易懂的天气预报。两者都声明了对象输出架构。

如何将它添加到 Claude Desktop、Cursor 或其他 MCP 客户端？

{
  "mcpServers": {
    "weather": { "command": "npx", "args": ["-y", "@thx93/mcp-weather-server"] }
  }
}

为什么要做这个项目？ 它最初是 MCP“构建一个服务”教程，之后又添加了类型化输出架构、只读注解、有界抓取、明确的失败约定和测试套件。

来源

项目始于 Build an MCP server 教程，之后又进行了扩展：类型化输出架构、只读工具注解、带有明确失败约定的有界抓取，以及测试套件。采用 ISC 许可证。