使用说明

MCP气象服务器

一种模型上下文协议（MCP）服务器，为美国各地提供实时天气警报和预报。采用FastMCP构建，由美国国家气象局（NWS）API提供动力。

作者

Matheus Remigio
联系人：matheus.remido@gmail.com

🌟 特性

天气警报：获取美国任何州的当前天气警报
天气预报：检索特定坐标的详细5天天气预报
实时数据：由官方国家气象局API提供支持
MCP集成：与MCP兼容的客户端和AI助手无缝集成
异步支持：内置async/await以获得最佳性能
错误处理：稳健的错误处理，优雅的回退

🚀 快速开始

先决条件

Python 3.13或更高版本
紫外线包管理器（推荐）
MCP兼容客户端（如Cursor IDE）

安装

克隆存储库

git clone https://github.com/msremigio/mcp-server-weather.git
cd mcp_weather

使用uv安装依赖项
```
uv sync
```
激活虚拟环境
```
uv shell
```

运行服务器

uv run weather.py

服务器将启动并通过stdio传输监听MCP协议消息。

🔧 配置

MCP客户端配置

将以下内容添加到MCP客户端配置中（例如。， mcp.json):

{
  "mcpServers": {
    "mcp_weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/mcp_weather/project",
        "run",
        "weather.py"
      ]
    }
  }
}

备注：更新 --directory 路径以匹配您的实际项目位置。

📚 api参考

可用工具

1.获取天气警报(`get_alerts`)

检索美国特定州的当前天气警报。

参数：

state （str）：两个字母的州缩写（例如，“CA”、“NY”、“TX”）

退货：

包含指定状态的所有活动警报的格式化字符串

示例响应：

Event: Severe Thunderstorm Warning
Area: Northern California
Severity: Severe
Description: Severe thunderstorms capable of producing large hail and damaging winds
Instructions: Move to an interior room on the lowest floor of a building

---

Event: Flash Flood Watch
Area: Southern California
Severity: Moderate
Description: Heavy rainfall may cause flash flooding
Instructions: Monitor weather conditions and be prepared to take action

2.获取天气预报(`get_forecast`)

检索特定坐标的5天天气预报。

参数：

latitude （str）：纬度坐标（十进制度数）
longitude （str）：经度坐标（十进制度数）

退货：

包含未来5个预测期的格式化字符串

示例响应：

Tonight:
- Temperature: 45°F
- Wind: 5 mph NW
- Forecast: Clear skies with light winds

---

Tomorrow:
- Temperature: 72°F
- Wind: 10 mph SW
- Forecast: Sunny and warm with increasing clouds in the afternoon

🏗️ 项目结构

mcp_weather/
├── weather.py          # Main MCP server implementation
├── main.py             # Simple entry point (placeholder)
├── pyproject.toml      # Project configuration and dependencies
├── mcp.json           # MCP client configuration template
├── README.md          # This file
├── uv.lock            # Dependency lock file
├── .python-version    # Python version specification
└── .venv/             # Virtual environment directory

🔌 依赖项

httpx：用于API请求的现代异步HTTP客户端
主控程序：模型上下文协议实现
FastMCP：用于构建MCP服务器的FastMCP框架

🌐 数据源

该项目使用美国国家气象局（NWS）API，它提供：

实时天气警报和警告
详细的天气预报
地理点数据
免费可靠的天气信息

🛠️ 发展

添加新工具

要添加新的天气相关工具，请执行以下操作：

在中创建一个新的异步函数 weather.py
用 @mcp.tool()
添加适当的类型提示和文档字符串
使用现有的辅助函数实现工具逻辑

测试

# Run the server in development mode
uv run weather.py

# Test with MCP client tools
# The server will respond to MCP protocol messages

📝 错误处理

服务器包括全面的错误处理：

HTTP请求失败
API响应验证
网络超时（30秒限制）
丢失数据的巧妙回退

🤝 贡献

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

📄 许可证

MIT许可证。

🙏 致谢

国家气象局用于提供天气数据API
MCP项目对于协议规范
FastMCP 对于服务器框架

📞 支持

对于问题、疑问或贡献：

在GitHub上打开一个问题
检查MCP文档
查看美国国家气象局API文件