Initialize MCP Server using Cursor IDE

MCP Weather Server

一个 Model Context Protocol（MCP）服务，为美国各地提供实时天气预警和预报。使用 FastMCP 构建，并由美国国家气象局（NWS）API 提供支持。

作者

Matheus Remigio
联系邮箱：[email protected]

🌟 功能

• 天气预警：获取美国任意州当前的天气预警
• 天气预报：根据指定坐标获取详细的 5 天天气预报
• 实时数据：由美国国家气象局官方 API 提供支持
• MCP 集成：与兼容 MCP 的客户端和 AI 助手无缝集成
• 异步支持：使用 async/await 构建，以实现最佳性能
• 错误处理：完善的错误处理机制，并提供优雅的回退方案

🚀 快速开始

前提条件

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

安装

1. 克隆代码库

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

2. 使用 uv 安装依赖项

   uv sync
   

3. 激活虚拟环境

   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 客户端
• mcp：Model Context Protocol 实现
• FastMCP：用于构建 MCP 服务的 FastMCP 框架

🌐 数据来源

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

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

🛠️ 开发

添加新工具

添加新的天气相关工具：

1. 在 weather.py 中创建新的异步函数
2. 使用 @mcp.tool() 为其添加装饰器
3. 添加合适的类型提示和文档字符串
4. 使用现有辅助函数实现工具逻辑

测试

# 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 秒限制）
• 缺少数据时的优雅回退方案

🤝 贡献

1. Fork 代码库
2. 创建功能分支
3. 进行更改
4. 如适用，添加测试
5. 提交拉取请求

📄 许可证

MIT License。

🙏 致谢

• 感谢美国国家气象局提供天气数据 API
• 感谢 MCP Project 提供协议规范
• 感谢 FastMCP 提供服务框架

📞 支持

如有问题、疑问或贡献：

• 在 GitHub 上提交 Issue
• 查阅 MCP 文档
• 查看美国国家气象局 API 文档

---

注意：此服务需要保持互联网连接，才能从 NWS API 获取天气数据。