🏄 冲浪预报 MCP 服务器

一个提供全球任何沿海地点全面冲浪预报的 MCP 服务器。获取当前条件及未来五天的预测，包括波高、周期、方向、风况以及智能冲浪质量评估。

✨ 功能

• 🌊 当前冲浪条件 - 实时波高、周期和方向
• 💨 风况 - 风速、方向和阵风（以节为单位）
• 🌡️ 温度数据 - 空气温度，用于规划您的冲浪时段
• 📅 5 天预报 - 每日预测，用于规划您的冲浪时段
• 📍 城市名称输入 - 只需提供一个城市名称（例如，“利沃诺”，“圣迭戈”）
• 🎯 自动地理编码 - 将城市名称转换为坐标
• 📊 结构化输出 - 清晰的 pydantic 模型，便于集成
• ✅ 数据验证 - 使用 pydantic 进行全面的数据质量验证
• 🏄 冲浪质量评估 - 对冲浪条件进行智能解读

🚀 快速开始

本地开发

1. 安装依赖：

pip install -r requirements.txt

2. 运行服务器：

python server.py

3. 使用 MCP 客户端连接（例如，Claude Desktop，Cline，MCP 客户端 SDK 等）

云部署

几分钟内部署到 fastmcp 云：

1. 创建一个 fastmcp 云账户
2. 关联您的 GitHub 账户
3. 部署此仓库
4. 您的服务器将立即对任何 MCP 客户端可用

🔧 MCP 原语

此服务器提供三个 MCP 原语：

工具

get_surf_forecast - 获取任何地点的全面冲浪预报

# MCP 工具调用
get_surf_forecast("Livorno")

# 返回经过验证的 SurfForecast 对象，包含：
# - 地点和坐标
# - 当前的波浪、风和温度条件
# - 5 天每日预报
# - 冲浪质量评估

资源

surf://info - 提供服务器信息，包括功能、数据来源和使用指南

提示

analyze_surf_conditions - 生成一个结构化的提示，用于分析特定地点的冲浪条件，引导 LLM 提供可操作的建议，包括质量评估、时间、趋势和技能水平指导

📁 项目架构

清晰地分离关注点，采用模块化设计：

surf-forecast-mcp/
├── server.py              # 包含工具定义的 MCP 服务器
├── models/
│   └── __init__.py       # 包含验证规则的数据结构
├── api/
│   ├── __init__.py       # API 客户端导出
│   ├── geocoding.py      # 地理编码 API 客户端（Nominatim）
│   ├── marine.py         # 海洋天气 API 客户端（Open-Meteo）
│   └── weather.py        # 天气预报 API 客户端（Open-Meteo）
├── services/
│   ├── __init__.py       # 服务导出
│   └── forecast.py       # 冲浪预报业务逻辑
├── example.py            # 使用示例
└── requirements.txt      # 依赖项

关注点分离：

• models/ - 数据结构和验证规则
• api/ - 外部集成，API 客户端
• services/ - 业务逻辑，数据转换
• server.py - MCP 接口，仅工具定义

📊 返回的数据

工具：get_surf_forecast

获取任何地点的全面冲浪预报。

参数：

• city_name (str): 沿海城市/地点的名称（例如，“利沃诺”，“比亚里茨”，“圣迭戈”）

返回结构化的预报，包含：

当前条件（每小时）

• 波高（米）
• 肿波高（米）
• 风波高（米）
• 波浪方向（度）
• 肿波方向（度）
• 波浪周期（秒）
• 肿波周期（秒）
• 风速（节）
• 风向（度）
• 阵风（节）
• 空气温度（摄氏度）

5 天预报（每日）

对于每一天：

• 最大波高（米）
• 最大肿波高（米）
• 最大风波高（米）
• 主导波浪方向（度）
• 主导肿波方向（度）
• 最大波浪周期（秒）
• 最大肿波周期（秒）
• 最大风速（节）
• 主导风向（度）
• 最大阵风（节）
• 最高温度（摄氏度）
• 最低温度（摄氏度）

其他信息

• 地点坐标（纬度/经度）
• 冲浪质量评估和备注

示例输出

工具返回优化后的文本，适合 LLM 上下文消费：

# 冲浪预报：意大利托斯卡纳利沃诺
位置：43.5484, 10.3116

## 当前条件
波浪：1.2 米（周期 9 秒）
  - 肿波：来自西面的 0.9 米
  - 风波：0.3 米
风：来自西面的 9 节（阵风 12 节）
温度：19°C

## 下几小时
03:00: 1.3 米波浪（肿波 1.0 米来自西面），西面的 10 节风
06:00: 1.4 米波浪（肿波 1.1 米来自西面），西面的 11 节风
09:00: 1.5 米波浪（肿波 1.2 米来自西南西面），北西面的 12 节风
12:00: 1.6 米波浪（肿波 1.2 米来自西南西面），北西面的 11 节风

## 5 天预报
2025-11-10:
  波浪：最大 1.5 米（肿波 1.1 米来自西面）
  风：西面的 12 节
  温度：16-22°C
2025-11-11:
  波浪：最大 1.8 米（肿波 1.4 米来自西南西面）
  风：北西面的 10 节
  温度：15-21°C
2025-11-12:
  波浪：最大 1.6 米（肿波 1.2 米来自西面）
  风：北面的 8 节
  温度：14-20°C
2025-11-13:
  波浪：最大 1.4 米（肿波 1.0 米来自西北西面）
  风：东北面的 11 节
  温度：15-19°C
2025-11-14:
  波浪：最大 1.7 米（肿波 1.3 米来自西面）
  风：东面的 13 节
  温度：16-21°C

## 冲浪质量
大多数冲浪者的良好波高 | 轻微的微风 - 良好的条件 | 中等周期 - 不错的波浪质量 | 肿波主导 - 更干净的条件

为什么这种格式？

• ✓ 简洁且易于阅读
• ✓ 上下文高效（约 200-300 个标记，而 JSON 需要 2000+）
• ✓ 易于 LLM 解析和推理

✅ 数据验证

所有数据均使用 Pydantic 模型进行验证。

🌐 数据来源

此服务器结合了两个 Open-Meteo API 的数据：

海洋天气 API

Open-Meteo 海洋 API 提供：

• 全球覆盖，分辨率 5 公里
• 每小时和每日波浪预报
• 多个波浪参数（显著高度、肿波、风波）
• 波浪方向和周期数据

天气预报 API

Open-Meteo 天气 API 提供：

• 风速、方向和阵风（以节为单位）
• 空气温度
• 每小时和每日预报

两个 API 在非商业用途下免费使用。

---

由 FastMCP 构建，并由 Open-Meteo 提供支持