Surf MCP Server

Surf MCP Server

面向冲浪者与网络冲浪者的 MCP 服务。

图示

视频演示

https://github.com/user-attachments/assets/0a4453e2-66df-4bf5-8366-8538cda366ed

功能

• 使用经纬度获取任意地点的潮汐信息
• 支持查询指定日期的潮汐信息
• 提供详细潮汐数据，包括高潮、低潮和站点信息
• 自动处理时区（UTC）

前置条件

• Python 3.x
• Storm Glass API 密钥

获取 Storm Glass API 密钥

1. 访问 Storm Glass
2. 点击“Try for Free”或“Sign In”创建账户
3. 注册后，你将收到 API 密钥

API 使用限额说明：

• 免费版：每天 10 次请求
• 提供付费套餐：
  • Small：每天 500 次请求（€19/月）
  • Medium：每天 5000 次请求（€49/月）
  • Large：每天 25,000 次请求（€129/月）
  • Enterprise：提供定制套餐

请根据使用需求选择套餐。免费版适合测试和个人使用。

安装

1. 克隆仓库：

git clone https://github.com/ravinahp/surf-mcp.git
cd surf-mcp

2. 使用 uv 安装依赖：

uv sync

注意：由于项目使用 pyproject.toml 管理依赖，我们使用 uv 而不是 pip。

配置为 MCP 服务

要将此工具添加为 MCP 服务，你需要修改 Claude 桌面应用的配置文件。此配置包含你的 Storm Glass API 密钥，因此无需单独设置。

配置文件位置取决于你的操作系统：

• MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

将以下配置添加到 JSON 文件中：

{
    "surf-mcp": {
        "command": "uv",
        "args": [
            "--directory",
            "/Users/YOUR_USERNAME/Code/surf-mcp",
            "run",
            "surf-mcp"
        ],
        "env": {
            "STORMGLASS_API_KEY": "your_api_key_here"
        }
    }
}

⚠️ 重要：

1. 将 YOUR_USERNAME 替换为你的实际系统用户名
2. 将 your_api_key_here 替换为你的实际 Storm Glass API 密钥
3. 确保目录路径与本地安装路径一致

部署

构建

准备软件包：

1. 同步依赖并更新锁定文件：

uv sync

2. 构建软件包：

uv build

这将在 dist/ 目录中生成发行包。

调试

由于 MCP 服务通过 stdio 运行，调试可能颇具挑战。为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

你可以使用以下命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/surf-mcp run surf-mcp

启动后，Inspector 会显示一个 URL，你可以在浏览器中访问该地址开始调试。

Inspector 提供：

• 实时请求/响应监控
• 输入/输出验证
• 错误跟踪
• 性能指标

使用方法

此服务提供一个用于获取潮汐信息的 FastMCP 工具：

@mcp.tool()
async def get_tides(latitude: float, longitude: float, date: str) -> str:
    """Get tide information for a specific location and date."""

参数：

• latitude：表示地点纬度的浮点数
• longitude：表示地点经度的浮点数
• date：格式为 YYYY-MM-DD 的日期字符串

响应示例：

Tide Times:
Time: 2024-01-20T00:30:00+00:00 (UTC)
Type: HIGH tide
Height: 1.52m

Time: 2024-01-20T06:45:00+00:00 (UTC)
Type: LOW tide
Height: 0.25m

Station Information:
Name: Sample Station
Distance: 20.5km from requested location

使用场景

示例 #1：寻找最佳冲浪时间

你可以使用此工具确定你最喜欢的海滩和最近站点的最佳冲浪时间。通常，涨潮期间（潮水上涨时），即高潮前约 2 小时，冲浪条件最佳。

给 Claude 的提示词示例：

注意：不同海滩的最佳潮汐条件可能不同，具体取决于其地理特征和浪点类型。此工具还会提供站点距离信息，应结合潮汐信息一并考虑。（也就是说，站点距离越远，误差可能越大；你也可以在提示词中向 Claude 询问这一点。）

错误处理

此服务包含完善的错误处理，涵盖：

• API 请求失败
• 坐标无效
• API 密钥缺失或无效
• 网络超时