USA NWS Weather MCP Server
一个基于Model Context Protocol (MCP)的服务器，提供美国国家气象局(NWS，https://www.weather.gov)的天气数据访问。注意，本工具不能提供美国本土之外的天气数据服务。
功能特性
- 当前天气: 获取指定位置的实时天气状况（支持地名和经纬度）
- 天气警报: 获取美国各州的当前天气警报
- 天气预报: 获取1-14天的天气预报（支持地名和经纬度）
- 小时预报: 获取1-48小时的小时预报（支持地名和经纬度）
- 雷达图像: 获取雷达站信息和雷达图像URL（支持地名和经纬度）
- 地理编码: 自动将地名转换为经纬度坐标
- 温度转换: 同时显示华氏度和摄氏度
安装要求
- Python 3.10+ (推荐使用Python 3.13+)
- uv - Python包管理工具
快速开始
1. 安装uv (如果尚未安装)
# 使用curl安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者使用Homebrew (macOS)
brew install uv
# 验证安装
uv --version2. 克隆项目
git clone
cd usa-nws-weather-mcp3. 创建虚拟环境并安装依赖
# 方法1: 使用uv sync自动创建虚拟环境
uv sync
# 方法2: 手动创建虚拟环境
uv venv .venv
source .venv/bin/activate # Linux/macOS
# 或 .venv\Scripts\activate # Windows
uv pip install -e .
# 如果遇到Python版本问题，可以指定Python版本
uv python pin 3.13.7
uv sync4. 验证安装
# 检查依赖是否安装成功
python -c "import httpx, mcp; print('依赖安装成功')"
# 运行测试
python -m pytest tests/ -v --asyncio-mode=auto5. 运行MCP服务器
# 方法1: 直接运行
python main.py
# 方法2: 使用uv运行
uv run python main.py6. 测试工具功能
# 运行示例演示
python example.py7. 运行测试（以 macOS 为例）
mac at macdeMacBook-Pro in ~/xgshi/code/mcp/usa-nws-weather-mcp (master●)
$ uv sync
Resolved 49 packages in 8ms
Uninstalled 14 packages in 205ms
- black==25.12.0
- iniconfig==2.3.0
- isort==7.0.0
- librt==0.7.5
- mypy==1.19.1
- mypy-extensions==1.1.0
- packaging==25.0
- pathspec==0.12.1
- platformdirs==4.5.1
- pluggy==1.6.0
- pygments==2.19.2
- pytest==9.0.2
- pytest-asyncio==1.3.0
- pytokens==0.3.0
(base)
mac at macdeMacBook-Pro in ~/xgshi/code/mcp/usa-nws-weather-mcp (master●)
$ python -c "import httpx, mcp; print('依赖安装成功')"
依赖安装成功
(base)
mac at macdeMacBook-Pro in ~/xgshi/code/mcp/usa-nws-weather-mcp (master●)
$ uv run python main.py&
[1] 10136
(base)
mac at macdeMacBook-Pro in ~/xgshi/code/mcp/usa-nws-weather-mcp (master●)
$ ============================================================
NWS天气MCP服务器
============================================================
此服务器设计为通过MCP协议与客户端通信。
它将在标准输入/输出(stdin/stdout)上等待MCP客户端连接。
要测试工具功能，请运行:
python example.py
要查看使用说明，请运行:
python run_server.py help
正在启动MCP服务器...
按Ctrl+C停止服务器
------------------------------------------------------------
[1] + 10136 suspended (tty input) uv run python main.py
(base)
mac at macdeMacBook-Pro in ~/xgshi/code/mcp/usa-nws-weather-mcp (master●)
$ python example.py
NWS天气MCP服务器示例
注意：这些演示需要访问NWS API和Nominatim地理编码服务，请确保网络连接正常。
新功能：支持地名输入和温度单位转换
请选择演示模式:
1. 演示所有工具（使用地名）
2. 演示特定工具（多个城市天气预报）
3. 演示新功能（地名支持和温度转换）
4. 退出
请输入选择 (1-4): 1
============================================================
NWS天气MCP服务器工具演示
============================================================
1. 获取当前天气（使用地名）:
----------------------------------------
[12/26/25 20:12:15] INFO HTTP Request: GET https://nominatim.openstreetmap.org/search?q=San+Francisco%2C+CA&format=json&limit=1&addressdetails=1 "HTTP/1.1 200 OK" _client.py:1740
[12/26/25 20:12:17] INFO HTTP Request: GET https://api.weather.gov/points/37.7879363,-122.4075201 "HTTP/1.1 301 Moved Permanently" _client.py:1740
[12/26/25 20:12:18] INFO HTTP Request: GET https://api.weather.gov/points/37.7879,-122.4075 "HTTP/1.1 200 OK" _client.py:1740
[12/26/25 20:12:19] INFO HTTP Request: GET https://api.weather.gov/gridpoints/MTR/85,106/stations "HTTP/1.1 200 OK" _client.py:1740
[12/26/25 20:12:20] INFO HTTP Request: GET https://api.weather.gov/stations/SFOC1/observations/latest "HTTP/1.1 200 OK" _client.py:1740
## 当前天气状况
位置: San Francisco, CA
**温度**: 12.51°C (54.5°F)
**体感温度**: None°C (None°F)
**湿度**: 68.315377134684%
**风速**: None m/s
**风向**: None°
**气压**: None hPa
**能见度**: None m
**天气状况**:
2. 获取天气警报:
----------------------------------------
[12/26/25 20:12:23] INFO HTTP Request: GET https://api.weather.gov/alerts/active/area/CA "HTTP/1.1 200 OK" _client.py:1740
## 当前天气预警
**事件**: High Surf Advisory
**区域**: San Francisco; Coastal North Bay Including Point Reyes National Seashore; San Francisco Peninsula Coast; Northern Monterey Bay; Southern Monterey Bay and Big Sur Coast
**严重性**: Minor
**描述**: * WHAT...Large breaking waves up to 25 feet, strong rip
currents and sneaker waves.
* WHERE...San Francisco, Coastal North Bay Including Point Reyes
National Seashore, San Francisco Peninsula Coast, Northern
Monterey Bay and Southern Monterey Bay and Big Sur Coa...
3. 获取天气预报 (3天，使用地名):
----------------------------------------
[12/26/25 20:12:27] INFO HTTP Request: GET https://api.weather.gov/points/37.7879363,-122.4075201 "HTTP/1.1 301 Moved Permanently" _client.py:1740
[12/26/25 20:12:28] INFO HTTP Request: GET https://api.weather.gov/points/37.7879,-122.4075 "HTTP/1.1 200 OK" _client.py:1740
[12/26/25 20:12:29] INFO HTTP Request: GET https://api.weather.gov/gridpoints/MTR/85,106/forecast "HTTP/1.1 200 OK" _client.py:1740
## 3天天气预报
位置: San Francisco, CA
### Overnight
**温度**: 51°F (10.6°C)
**风力**: 18 mph SSW
**详细预报**: Partly cloudy, with a low around 51. South southwest wind around 18 mph, with gusts as high as 30 mph.
---
### Friday
**温度**: 56°F (13.3°C)
**风力**: 14 to 18 mph SSW
**详细预报**: A chance of rain showers between 9am and 1pm, then a chance of showers and thunderstorms. Partly sunny. High near 56, with temperatures falling to around 52 in the afternoon. South southwest wind 14 to 18 mph, with gusts a...
4. 获取小时预报 (12小时，使用地名):
----------------------------------------
[12/26/25 20:12:31] INFO HTTP Request: GET https://api.weather.gov/points/37.7879363,-122.4075201 "HTTP/1.1 301 Moved Permanently" _client.py:1740
INFO HTTP Request: GET https://api.weather.gov/points/37.7879,-122.4075 "HTTP/1.1 200 OK" _client.py:1740
[12/26/25 20:12:32] INFO HTTP Request: GET https://api.weather.gov/gridpoints/MTR/85,106/forecast/hourly "HTTP/1.1 200 OK" _client.py:1740
## 12小时预报
位置: San Francisco, CA
**时间**: 03:00 - 04:00
**温度**: 52°F (11.1°C)
**风力**: 18 mph S
**预报**: Mostly Cloudy
---
**时间**: 04:00 - 05:00
**温度**: 52°F (11.1°C)
**风力**: 18 mph SSW
**预报**: Partly Cloudy
---
**时间**: 05:00 - 06:00
**温度**: 52°F (11.1°C)
**风力**: 18 mph S
**预报**: Partly Cloudy
---
**时间**: 06:00 - 07:00
**温度**: 53°F (11.7°C)
**风力**: 17 mph S
**预报**: Partly Sunny
---
**时间**: 07:00 - 08:00
**温度**: 52°F (11.1°C)
**风力**: 16 mph S
**预报**: Partly Sunny
---
**时间**: 08:00 - 09:00...
5. 获取雷达图像（使用地名）:
----------------------------------------
[12/26/25 20:12:34] INFO HTTP Request: GET https://api.weather.gov/points/37.7879363,-122.4075201 "HTTP/1.1 301 Moved Permanently" _client.py:1740
INFO HTTP Request: GET https://api.weather.gov/points/37.7879,-122.4075 "HTTP/1.1 200 OK" _client.py:1740
## 雷达图像信息
位置: San Francisco, CA
**雷达站**: KMUX
**雷达图像URL**: https://radar.weather.gov/ridge/standard/KMUX_loop.gif
*注意：这是一个示例雷达图像URL，实际可用性取决于雷达站和数据可用性。*
============================================================
演示完成！
============================================================
(base)
mac at macdeMacBook-Pro in ~/xgshi/code/mcp/usa-nws-weather-mcp (master●)
$MCP工具列表
1. 获取当前天气 (get_current_weather)
获取指定位置的当前天气状况。
参数（二选一）:
- 方式1:
latitude(float) 和longitude(float) - 经纬度坐标 - 方式2:
location(str) - 地名，例如 "Mountain View, CA"
注意: 如果同时提供location和经纬度参数，将优先使用location参数。
示例:
# 方式1: 使用经纬度获取旧金山的当前天气
get_current_weather(latitude=37.7749, longitude=-122.4194)
# 方式2: 使用地名获取旧金山的当前天气
get_current_weather(location="San Francisco, CA")
# 方式3: 使用地名获取纽约的当前天气
get_current_weather(location="New York, NY")输出特点:
- 同时显示摄氏度和华氏度温度
- 包含位置信息
- 显示体感温度、湿度、风速、风向、气压、能见度等
2. 获取天气警报 (get_alerts)
获取美国某个州当前生效的天气预警信息。
参数:
state(str): 两个字母的美国州代码，例如：CA, NY
示例:
# 获取加利福尼亚州的天气警报
get_alerts(state="CA")
# 获取纽约州的天气警报
get_alerts(state="NY")
# 获取德克萨斯州的天气警报
get_alerts(state="TX")输出特点:
- 显示预警事件、区域、严重性、描述和指令
- 格式化易于阅读的Markdown格式
3. 获取天气预报 (get_forecast)
根据给定的位置获取指定天数的天气预报。
参数:
latitude(float, 可选): 纬度，范围：-90 到 90longitude(float, 可选): 经度，范围：-180 到 180location(str, 可选): 地名，例如 "Mountain View, CA"days(int): 预报天数，范围：1 到 14，默认为5
注意: 必须提供location或经纬度参数之一。
示例:
# 方式1: 使用经纬度获取纽约市7天天气预报
get_forecast(latitude=40.7128, longitude=-74.0060, days=7)
# 方式2: 使用地名获取纽约市7天天气预报
get_forecast(location="New York, NY", days=7)
# 方式3: 获取芝加哥3天天气预报
get_forecast(location="Chicago, IL", days=3)输出特点:
- 同时显示华氏度和摄氏度温度
- 包含位置信息
- 显示风力、详细预报等信息
4. 获取小时预报 (get_hourly_forecast)
获取指定地点的小时预报。
参数:
latitude(float, 可选): 纬度，范围：-90 到 90longitude(float, 可选): 经度，范围：-180 到 180location(str, 可选): 地名，例如 "Mountain View, CA"hours(int): 预报小时数，范围：1 到 48，默认为12
注意: 必须提供location或经纬度参数之一。
示例:
# 方式1: 使用经纬度获取芝加哥24小时预报
get_hourly_forecast(latitude=41.8781, longitude=-87.6298, hours=24)
# 方式2: 使用地名获取芝加哥24小时预报
get_hourly_forecast(location="Chicago, IL", hours=24)
# 方式3: 获取洛杉矶12小时预报
get_hourly_forecast(location="Los Angeles, CA", hours=12)输出特点:
- 同时显示华氏度和摄氏度温度
- 包含位置信息
- 显示时间范围、风力、简短预报等信息
5. 获取雷达图像 (get_radar_image)
获取指定地点的雷达图像URL。
参数:
latitude(float, 可选): 纬度，范围：-90 到 90longitude(float, 可选): 经度，范围：-180 到 180location(str, 可选): 地名，例如 "Mountain View, CA"
注意: 必须提供location或经纬度参数之一。
示例:
# 方式1: 使用经纬度获取德克萨斯州奥斯汀的雷达图像
get_radar_image(latitude=30.2672, longitude=-97.7431)
# 方式2: 使用地名获取德克萨斯州奥斯汀的雷达图像
get_radar_image(location="Austin, TX")
# 方式3: 获取西雅图的雷达图像
get_radar_image(location="Seattle, WA")输出特点:
- 包含位置信息
- 显示雷达站代码和雷达图像URL
- 提供使用说明和注意事项
技术细节
数据源
- 天气数据来自美国国家气象局(NWS)的公共API
- 地理编码数据来自OpenStreetMap的Nominatim服务
- NWS API基础URL:
https://api.weather.gov - Nominatim API基础URL:
https://nominatim.openstreetmap.org - 无需API密钥，但需要设置合适的User-Agent
地理编码功能
- 支持将地名自动转换为经纬度坐标
- 使用Nominatim服务进行地理编码
- 内置重试机制（最多3次重试）
- 速率限制保护（1次/秒，满足Nominatim要求）
- 本地缓存避免重复请求
温度显示
- 所有温度信息同时显示华氏度和摄氏度
- 精确的温度转换（保留一位小数）
- 支持华氏度到摄氏度的双向转换
输出格式
- 所有工具返回Markdown格式的响应
- 包含结构化的天气信息
- 易于阅读和解析
- 包含位置信息和温度单位转换
错误处理
- 网络请求超时处理（30秒）
- API响应错误处理
- 输入参数验证
- 友好的错误消息
- 地理编码失败时的明确提示
开发
项目结构
usa-nws-weather-mcp/
├── main.py # 主程序文件（包含所有MCP工具）
├── pyproject.toml # 项目配置和依赖
├── README.md # 项目文档
├── run_server.py # 服务器运行脚本
├── example.py # 示例演示脚本
├── tests/ # 测试目录
│ ├── conftest.py # 测试配置
│ └── test_main.py # 主测试文件
└── .gitignore # Git忽略文件核心功能模块
- 地理编码模块: 将地名转换为经纬度坐标
- 温度转换模块: 华氏度与摄氏度转换
- NWS API客户端: 与NWS API通信
- MCP工具层: 提供5个天气工具
- 错误处理层: 统一的错误处理机制
运行单元测试（pytest）
# 安装开发依赖
uv sync --extra dev
# 运行测试
uv run pytest tests/ -v
# 或者直接使用系统Python运行测试
python -m pytest tests/ -v --asyncio-mode=auto以下为屏幕输出
$ python -m pytest tests/ -v --asyncio-mode=auto
==================================================================================================== test session starts =====================================================================================================
platform darwin -- Python 3.13.7, pytest-9.0.1, pluggy-1.6.0 -- /usr/local/bin/python3
cachedir: .pytest_cache
rootdir: /Users/mac/xgshi/code/mcp/usa-nws-weather-mcp
configfile: pyproject.toml
plugins: anyio-4.11.0, asyncio-1.3.0, langsmith-0.4.56
asyncio: mode=Mode.AUTO, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
collected 22 items
tests/test_main.py::TestHelperFunctions::test_format_alert PASSED [ 4%]
tests/test_main.py::TestHelperFunctions::test_format_alert_missing_fields PASSED [ 9%]
tests/test_main.py::TestHelperFunctions::test_fahrenheit_to_celsius PASSED [ 13%]
tests/test_main.py::TestHelperFunctions::test_location_model PASSED [ 18%]
tests/test_main.py::TestGeocodingFunctions::test_geocode_location_success SKIPPED (模拟测试复杂，实际功能已验证正常工作) [ 22%]
tests/test_main.py::TestGeocodingFunctions::test_geocode_location_failure PASSED [ 27%]
tests/test_main.py::TestGeocodingFunctions::test_geocode_location_retry SKIPPED (模拟测试复杂，实际功能已验证正常工作) [ 31%]
tests/test_main.py::TestGeocodingFunctions::test_get_coordinates_with_location PASSED [ 36%]
tests/test_main.py::TestGeocodingFunctions::test_get_coordinates_with_lat_lon PASSED [ 40%]
tests/test_main.py::TestGeocodingFunctions::test_get_coordinates_none PASSED [ 45%]
tests/test_main.py::TestMCPTools::test_get_current_weather_with_coordinates PASSED [ 50%]
tests/test_main.py::TestMCPTools::test_get_current_weather_with_location PASSED [ 54%]
tests/test_main.py::TestMCPTools::test_get_current_weather_invalid_params PASSED [ 59%]
tests/test_main.py::TestMCPTools::test_get_current_weather_geocode_failure PASSED [ 63%]
tests/test_main.py::TestMCPTools::test_get_forecast_with_location PASSED [ 68%]
tests/test_main.py::TestMCPTools::test_get_forecast_with_celsius PASSED [ 72%]
tests/test_main.py::TestMCPTools::test_get_hourly_forecast_with_location PASSED [ 77%]
tests/test_main.py::TestMCPTools::test_get_radar_image_with_location PASSED [ 81%]
tests/test_main.py::TestMCPTools::test_get_alerts_success PASSED [ 86%]
tests/test_main.py::TestMCPTools::test_get_alerts_no_alerts PASSED [ 90%]
tests/test_main.py::TestMCPTools::test_get_forecast_invalid_days PASSED [ 95%]
tests/test_main.py::TestMCPTools::test_get_hourly_forecast_invalid_hours PASSED [100%]
=============================================================================================== 20 passed, 2 skipped in 4.51s ================================================================================================
(base)代码质量
# 代码格式化
uv run black main.py tests/
# 导入排序
uv run isort main.py tests/
# 类型检查
uv run mypy main.py配置
User-Agent配置
服务器使用以下User-Agent格式：
usa-nws-weather-mcp/1.0 (https://github.com/your-username/usa-nws-weather-mcp)您可以在main.py中修改USER_AGENT常量以使用您自己的联系信息。
本地部署配置
要配置Claude Desktop或其他MCP客户端使用此服务器，请参考以下文件：
studio-configuration-example.json: 基础配置示例CONFIGURATION.md: 详细配置指南
配置步骤：
- 复制
studio-configuration-example.json中的配置 - 根据您的路径修改配置
- 将配置添加到Claude Desktop的配置文件中
- 重启Claude Desktop
虚拟环境管理
项目使用uv进行依赖管理，虚拟环境默认创建在.venv目录中：
# 激活虚拟环境
source .venv/bin/activate # Linux/macOS
# 或 .venv\Scripts\activate # Windows
# 安装开发依赖
uv sync --extra dev
# 更新依赖
uv sync --upgrade
# 清理缓存
uv cache clean许可证
本项目采用MIT许可证。详见LICENSE文件。
贡献
欢迎提交Issue和Pull Request！
免责声明
- 本工具提供的数据来自美国国家气象局(NWS)的公共API
- 数据准确性取决于NWS API的可用性和更新频率
- 开发者不对因使用本工具导致的任何损失或损害负责