📌Overview

Purpose: The Surf MCP Server aims to provide surfers with accurate tide information through a user-friendly interface while seamlessly integrating with web applications.

Overview: This framework allows users to fetch real-time tide data based on geographical coordinates. It is designed for both individual surfers and developers looking to enhance their applications with tide-related data.

Key Features:

Tide Information Fetching: Users can retrieve tide information by inputting latitude and longitude, ensuring precise location-based data.
Date-Specific Queries: The server supports queries for specific dates, allowing users to plan surfing trips based on forecasted tide conditions.
Detailed Data Outputs: Users receive comprehensive tide details, including high and low tides and associated station information, enriching their understanding of local tide patterns.
Automatic Time Zone Management: The system handles time zone conversions, delivering all times in UTC for consistency and ease of use.

Surf MCP Server

MCP server for people who surf waves and the web.

Video Demo

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

Features

Fetch tide information for any location using latitude and longitude
Support for date-specific tide queries
Detailed tide data including high/low tides and station information
Automatic time zone handling (UTC)

Prerequisites

Python 3.x
Storm Glass API key

Getting Your Storm Glass API Key

Visit https://stormglass.io/
Click "Try for Free" or "Sign In" to create an account
Once registered, you'll receive your API key

Note on API Usage Limits:

Free tier: 10 requests per day
Paid plans available:
- Small: 500 requests/day (€19/month)
- Medium: 5000 requests/day (€49/month)
- Large: 25,000 requests/day (€129/month)
- Enterprise: Custom plans available

Choose a plan based on your usage requirements. The free tier is suitable for testing and personal use.

Installation

Clone the repository:

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

Install dependencies using uv:

uv sync

Note: uv is used instead of pip since the project uses pyproject.toml for dependency management.

Configure as MCP Server

To add this tool as an MCP server, modify your Claude desktop configuration file. This setup includes your Storm Glass API key.

Configuration file locations:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Add the following configuration:

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

Important:

Replace YOUR_USERNAME with your actual system username
Replace your_api_key_here with your actual Storm Glass API key
Ensure the directory path matches your local installation

Deployment

Building

Prepare the package:

Sync dependencies and update lockfile:

uv sync

Build package:

uv build

Distributions will be created in the dist/ directory.

Debugging

MCP servers run over stdio, making debugging challenging. Use the MCP Inspector for the best experience.

Launch the MCP Inspector with:

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

The Inspector opens a URL in your browser, providing:

Real-time request/response monitoring
Input/output validation
Error tracking
Performance metrics

Usage

The service provides a FastMCP tool for getting tide information:

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

Parameters:

latitude: Float value representing the location's latitude
longitude: Float value representing the location's longitude
date: Date string in YYYY-MM-DD format

Example Response:

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

Use Cases

Example #1: Finding the Best Surf Time

Determine the optimal surfing time at your favorite beach and the closest station. Typically, the best surfing conditions are during incoming (rising) tides, about 2 hours before high tide.

Note: Different beaches may have different optimal tide conditions based on their geography and break type. The tool also provides station distance information. Longer station distance may increase chance of inaccuracy.

Error Handling

The service includes robust error handling for:

API request failures
Invalid coordinates
Missing or invalid API keys
Network timeouts