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. 点击“免费试用”或“登录”以创建账户
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服务器通过标准I/O运行，调试可能会很困难。为了获得最佳的调试体验，我们强烈建议使用MCP Inspector。

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

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

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

Inspector提供了：

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

使用

服务提供了一个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.52米

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

站点信息：
名称：示例站点
距离：距请求位置20.5公里

使用场景

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

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

给Claude的示例提示：

<img width="693" alt="2025年1月7日 下午12:55:47截图" src="https://gips1.baidu.com/it/u=516598378,4020416741&fm=3081&app=3081&f=PNG?w=1386&h=1222" />

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

错误处理

服务包含强大的错误处理功能，针对：

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