Surf MCP 服务器

为冲浪者和网络冲浪者打造的 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. 点击“免费试用”或“登录”创建账户
3. 注册后，您将收到 API 密钥

API 使用限制说明：

• 免费层级：每天 10 次请求
• 付费计划：
  • 小型：每天 500 次请求（€19/月）
  • 中型：每天 5000 次请求（€49/月）
  • 大型：每天 25,000 次请求（€129/月）
  • 企业级：可定制计划

根据您的使用需求选择计划。免费层级适合测试和个人使用。

安装

1. 克隆仓库：

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

2. 使用 uv 安装依赖：

uv sync

注意：我们使用 uv 而不是 pip，因为项目使用 pyproject.toml 进行依赖管理。

配置为 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 检查器。

您可以使用以下命令启动 MCP 检查器：

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

启动后，检查器将显示一个 URL，您可以在浏览器中访问以开始调试。

检查器提供：

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

使用

该服务提供了一个 FastMCP 工具来获取潮汐信息：

@mcp.tool()
async def get_tides(latitude: float, longitude: float, date: str) -> str:
    """获取特定地点和日期的潮汐信息。"""

参数：

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

示例响应：

潮汐时间：
时间: 2024-01-20T00:30:00+00:00 (UTC)
类型: 高潮
高度: 1.52m

时间: 2024-01-20T06:45:00+00:00 (UTC)
类型: 低潮
高度: 0.25m

站点信息：
名称: 示例站点
距离: 距离请求地点 20.5km

使用案例

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

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

向 Claude 提出的示例提示：

注意：不同的海滩可能根据其特定的地理和破浪类型有不同的最佳潮汐条件。此工具还提供站点距离信息，应与潮汐信息一起考虑。（即，较长的站点距离意味着更高的不准确性 - 您也可以在提示时向 Claude 询问这一点）。

错误处理

该服务包括对以下情况的强大错误处理：

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